EnginFrame Administrator`s Reference

Administrator's Reference
Version 2010
Copyright
Copyright © 2000-2010, NICE s.r.l.
All right reserved.
We'd Like to Hear from You
You can help us make this document better by telling us what you think of the content, organization, and usefulness of
the information. If you find an error or just want to make a suggestion for improving this document, please address your
comments to <documentation@enginframe.com>. Please send only comments regarding NICE documentation.
For product support, contact <support@enginframe.com>.
Although the information in this document has been carefully reviewed, NICE s.r.l. ("NICE") does not warrant it to
be free of errors or omissions. NICE reserves the right to make corrections, updates, revisions, or changes to the
information in this document.
UNLESS OTHERWISE EXPRESSLY STATED BY NICE, THE PROGRAM DESCRIBED IN THIS DOCUMENT IS
PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. IN NO EVENT WILL NICE BE LIABLE TO ANYONE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES, INCLUDING WITHOUT LIMITATION ANY LOST PROFITS, DATA, OR SAVINGS,
ARISING OUT OF THE USE OF OR INABILITY TO USE THIS PROGRAM.
Document Redistribution and Translation
This document is protected by copyright and you may not redistribute or translate it into another language, in part or
in whole, without the express written permission of NICE s.r.l.
Trademarks
EnginFrame, Remote File Browsing, Service Definition File, EnginFrame Agent are registered trademarks or
trademarks of NICE s.r.l. in Italy and other countries.
Apache, Tomcat are either registered trademarks or trademarks of the Apache Software Foundation in the United
States and/or other countries.
Java and all Java-based trademarks are registered trademarks or trademarks of Sun Microsystems, Inc. in the United
States and other countries.
Unix is a registered trademark of The Open Group in the United States and other countries.
Linux is the registered trademark of Linus Torvalds in the United States and other countries.
Microsoft, Windows and Internet Explorer are either registered trademarks or trademarks of Microsoft Corporation in
the United States and other countries.
Solaris is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and/or other countries.
HP-UX is a trademark or registered trademark of Hewlett-Packard Company in the United States and/or other countries.
AIX is a trademark or registered trademark of International Business Machines Corporation in the United States and/
or other countries.
Firefox and Mozilla are trademarks or registered trademarks of the Mozilla Foundation in the United States and/or
other countries.
Mac OS X and Safari are trademarks or registered trademarks of Apple, Inc. in the United States and other countries.
Other products or services mentioned in this document are identified by the trademarks or service marks of their
respective owners.
Last Update
November 8, 2011 (rev. 21722)
Latest Version
http://www.enginframe.com/docs
Contents
Welcome .......................................................................................................................... v
About This Guide ...................................................................................................... v
Who Should Read This Guide .......................................................................... v
Learn About NICE Products ..................................................................................... vi
World Wide Web .............................................................................................. vi
NICE EnginFrame Training .............................................................................. vi
NICE EnginFrame Documentation ................................................................... vi
Get Technical Support ............................................................................................. vii
NICE Support Contacts ................................................................................... vii
Collect Support Information ............................................................................. vii
1. Global Configuration .................................................................................................. 1
enginframe.conf ......................................................................................................... 1
2. Server Configuration .................................................................................................. 5
server.conf ................................................................................................................. 5
mime-types.xml ......................................................................................................... 9
3. Agent Configuration ................................................................................................. 13
agent.conf ................................................................................................................ 13
ef_java.policy ........................................................................................................... 17
4. Logging Configuration ............................................................................................. 19
Priorities .................................................................................................................. 19
Categories ............................................................................................................... 20
Log Targets ............................................................................................................. 20
Formatters ............................................................................................................... 20
log.agent.xconf ........................................................................................................ 22
log.server.xconf ....................................................................................................... 23
Configuration Examples .......................................................................................... 25
5. EnginFrame Authentication XML ............................................................................ 27
Login Tags .............................................................................................................. 27
<ef:command> ................................................................................................. 27
<ef:error> ......................................................................................................... 28
<ef:login> ......................................................................................................... 29
<ef:message> .................................................................................................. 30
<ef:signature> .................................................................................................. 30
<ef:title> ........................................................................................................... 31
6. Authorization System Configuration ...................................................................... 33
authorization.xconf .................................................................................................. 33
Condition Based ACL ............................................................................................. 36
7. HTTP Basic Authentication Configuration ............................................................. 39
Protecting the EnginFrame Web Application .......................................................... 40
Using the Internal Credentials Database ................................................................ 40
Using Apache Credentials ...................................................................................... 40
Using LDAP Credentials ......................................................................................... 41
8. Post Processor Configuration ................................................................................. 43
processor.conf ......................................................................................................... 43
EnginFrame Administrator's Reference
iii
Welcome
About This Guide
This is "EnginFrame Administrator's Guide" companion providing reference information for NICE
EnginFrame portal administrators.
Who Should Read This Guide
This guide is intended for system administrators who administer and maintain an instance of the
NICE EnginFrame portal but are not necessarily creating new services.
EnginFrame Administrator's Reference
v
Learn About NICE Products
Learn About NICE Products
World Wide Web
You can find the latest information about NICE EnginFrame on its web site
http://www.enginframe.com.
For more information about other NICE products and about the professional services provided by
NICE you can refer to the company's web site http://www.nice-software.com.
Report problems accessing the aforementioned web sites to <support@enginframe.com>.
NICE EnginFrame Training
Training classes offered by NICE can help you master the skills needed to productively configure,
manage, and maintain your EnginFrame Portal.
Classes are available at our corporate headquarters and other NICE locations.
Customized on-site classes are also available.
Find out more about NICE training at http://www.nice-software.com or for further details
contact <info@nice-software.com>.
NICE EnginFrame Documentation
The latest NICE EnginFrame documentation is available at
http://www.enginframe.com/docs.
Visit NICE web site at http://www.nice-software.com and get your personal access code
to the documentation area or contact <documentation@enginframe.com>.
vi
EnginFrame Administrator's Reference
Get Technical Support
Get Technical Support
Contact NICE or your EnginFrame reseller for technical support.
NICE Support Contacts
Use one of the following to contact NICE technical support.
Email
<support@enginframe.com>
World Wide Web
http://www.enginframe.com
Phone
+39 0141 901516
Mail
NICE Support
c/o NICE s.r.l.
Via Milliavacca, 9
14100 Asti
Italy
When contacting NICE, please include your company's full name.
Collect Support Information
Please use "Support/Collect support info" service from administration portal to collect some
preliminary data that could help NICE support team speed up time to process your support request.
Refer to EnginFrame Administrator's Guide for more details.
The output of this service is a compressed archive containing all the gathered information. Please
send the compressed archive to NICE support team attached to your request.
EnginFrame Administrator's Reference
vii
1
Global Configuration
enginframe.conf
EnginFrame Portal global settings can be found in the following file:
• NICE_ROOT/conf/enginframe.conf
where NICE_ROOT is the directory containing the installed software bundle.
The description of the global configuration parameters follows.
EF_NICE
This is the EnginFrame bundle top directory. You can chose this directory at installation time.
The installer does not copy files outside this directory unless you specify different installation
directories for the following components.
DYNAMIC_NICE
This parameter is used as top directory for some of the following customizable directories. By
default it is defined as
DYNAMIC_NICE="${EF_NICE}"
. You can point to any other directory fits with the following permissions:
rwxr-xr-x (755) root:root
.
EF_ROOT
This is the EnginFrame top-level directory. Modify this value if you move EnginFrame
installation to a different directory. By default it is defined as
EF_ROOT="${EF_NICE}/enginframe"
.
EF_DYNAMIC_ROOT
This parameter is used as top directory for some of the following customizable directories. By
default it is defined as
EnginFrame Administrator's Reference
1
enginframe.conf
EF_DYNAMIC_ROOT="${DYNAMIC_NICE}/enginframe"
. You can point to any other directory fits with the following permissions:
rwxr-xr-x (755) root:root
.
CATALINA_DYNAMIC_ROOT
This parameter is used as top directory for some of the following customizable directories under
Tomcat. By default it is defined as
CATALINA_DYNAMIC_ROOT="${DYNAMIC_NICE}/tomcat"
. You can point to any other directory fits with the following permissions:
rwxr-xr-x (755) root:root
.
CATALINA_TMPDIR
This is Tomcat's temporary directory. By default it is defined as
CATALINA_TMPDIR="${CATALINA_DYNAMIC_ROOT}/temp"
. You can point to any other directory fits with the following permissions:
rwxr-x--- (750) efnobody:efadmin
.
CATALINA_LOGDIR
This directory contains Tomcat's log files. By default it is defined as
CATALINA_LOGDIR="${CATALINA_DYNAMIC_ROOT}/logs"
. You can point to any other directory fits with the following permissions:
rwxr-x--- (750) efnobody:efadmin
.
CATALINA_WORKDIR
This is Tomcat's work directory. By default it is defined as
CATALINA_WORKDIR="${CATALINA_DYNAMIC_ROOT=}/work"
. You can point to any other directory fits with the following permissions:
rwxr-x--- (750) efnobody:efadmin
.
2
EnginFrame Administrator's Reference
enginframe.conf
EF_LOGDIR
This directory contains EnginFrame's log files. By default it is defined as
EF_LOGDIR="${EF_DYNAMIC_ROOT}/logs"
. You can point to any other directory fits with the following permissions:
rwxr-x--- (750) and this ownership: efnobody:efadmin
.
EF_TEMPDIR
EnginFrame's temporary directory. By default it is defined as
EF_TEMPDIR="${EF_DYNAMIC_ROOT}/tmp"
. You can point to any other directory fits with the following permissions:
rwxr-xr-x (755) efnobody:root
.
EF_SPOOLERDIR
This directory contains EnginFrame's spoolers. By default it is defined as
EF_SPOOLERDIR="${EF_DYNAMIC_ROOT}/spoolers"
. You can point to any other directory fits with the following permissions:
rwxr-xr-x (755) efnobody:root
.
EF_REPOSITORYDIR
This directory contains EnginFrame's repositories. By default it is defined as
EF_REPOSITORYDIR="${EF_DYNAMIC_ROOT}/repository"
. You can point to any other directory fits with the following permissions:
rwxr-x--- (750) efnobody:root
.
JAVA_HOME
Specifies JDK's root directory. It must be an absolute path. It is used to run EnginFrame. E.g.
JAVA_HOME="/opt/java/jdk"
TOMCAT_USER
Identifies user running EnginFrame Server. The system switches to this user who starts Apache
Tomcat servlet container and thus EnginFrame Server. E.g.
EnginFrame Administrator's Reference
3
enginframe.conf
TOMCAT_USER="efnobody"
COMMON_JAVA_OPTIONS
Defines list of parameters passed to JDK starting EnginFrame Server and EnginFrame Agent.
Common Java settings can be added to this variable. E.g.
COMMON_JAVA_OPTIONS="-Dcustom.var=my.custom.value"
SERVER_JAVA_OPTIONS
Defines list of parameters passed to JDK starting EnginFrame Server. Changes to server Java
settings can be added to this variable. E.g.
SERVER_JAVA_OPTIONS="-server -Xms32m -Xmx200m"
AGENT_JAVA_OPTIONS
Defines list of parameters passed to JDK starting EnginFrame Agent. Changes to agent Java
settings can be added to this variable. E.g.
AGENT_JAVA_OPTIONS="-server -Xms32m –Xmx128m"
EF_LOCALE
Specifies locale used to run EnginFrame. E.g.
EF_LOCALE="C"
A locale is a set of information addressing linguistic and cultural requirements that corresponds to
a given language and country. Traditionally, the data associated with a locale provides support for
formatting and parsing of dates, times, numbers, and currencies, etc. Any valid locae prodcued by
locale -a
can be used here. It is important that it can handle UTF-8 charset since EnginFrame relies on it.
4
EnginFrame Administrator's Reference
2
Server Configuration
The EnginFrame Server configuration involves two files:
• EF_ROOT/conf/server.conf
• EF_ROOT/conf/mime-types.xml
Note
EnginFrame configuration files contain variables based on other variables
using the syntax ${property_name}. Every time EnginFrame encounters
a dynamic variable it expands its value using property_name's value.
Variable property_name could be defined in a configuration file or could
have been passed to JDK at startup via property definition,
i.e. -Dproperty_name=property_value.
If enginframe.conf contains EF_ROOT=/opt/nice/enginframe
then ${EF_ROOT}/etc is expanded to /opt/nice/enginframe/
etc. Changing EF_ROOT to /usr/local/ef leaves ${EF_ROOT}/etc
unmodified since it is correctly expanded to /usr/local/ef/etc when
used.
Example 2.1. EF_ROOT expansion
server.conf
Here follows a description of the parameters and how to use them.
ef.default.context
Specifies execution context used if ef:action, being executed, does not contain one.
The default value is os.
ef.reaper.sleep.time
Specifies sleep time, in minutes, for the low priority thread that cleans up spoolers. This thread
wakes up every ef.reaper.sleep.time minutes to start reap cycle.
The default value is 30 (i.e., half an hour) minutes.
EnginFrame Administrator's Reference
5
server.conf
ef.processor.conf
Specifies EnginFrame Post Processor configuration file. The processor handles EnginFrame
Server Page (EFSP) tags.
ef.output.limit
Specifies maximum number of bytes an output process can return. Output stream is truncated if
this limit is exceeded.
The default value is 1 MB.
ef.reset.repository.onstartup
Enables repository entries to be removed if their spooler counterpart directory is not available at
start-up time. Spooler data is not deleted.
The default value is false.
ef.write.timing.comment
Enables writing a comment at bottom of HTML page with time, in milliseconds, elapsed to serve
request.
The default value is true.
ef.error.layout
Defines error XSL absolute path. It is used to deliver system error pages to end-users.
The default value is EF_ROOT/lib/xsl/com.enginframe.error.xsl.
ws.session.timeout
Defines Web Services application session timeout in seconds. If this property is missing it defaults
to system session timeout configured in web.xml.
The default value is 1800 (i.e., half an hour) seconds.
ef.spooler.default.project
Defines default name of projects associated to spoolers.
The default value is Default.
ef.compressable.mime.types
This value is a comma separated list of MIME types for which HTTP compression may
be used. If you want to disable compression, define the property with an empty value:
ef.compressable.mime.types=
The default value is text/html,text/xml,text/css,text/plain,text/javascript,application/
javascript,application/x-javascript.
ef.cacheable.mime.types
This value is a comma separated list of MIME types for which HTTP cache expiration may
be used. If you want to disable cache expiration, define the property with an empty value:
ef.cacheable.mime.types=
The default value is text/javascript,application/javascript,application/x-javascript,text/
css,image/vnd.microsoft.icon,image/png,image/jpeg,image/gif.
ef.cacheable.mime.types.period
Specifies, in seconds, MIME types cache expiration period.
The default value is 1 year.
6
EnginFrame Administrator's Reference
server.conf
ef.download.manager
Specifies download manager. The value can be local or remote.
local - the classic download procedure accomplished by EnginFrame Server; files must be
readabel by EF_NOBODY
remote - file contents are provided by the EnginFrame Agent on behalf of user making request,
through the use of external commands
The default value is remote.
ef.download.stream.sleep.time
Specifies time to wait, in seconds, before checking again for available bytes during streaming
download.
The default value is 5 seconds.
ef.download.stream.inactivity.timeout
Specifies maximum time to wait, in seconds, before quitting reading streamed file. This timeout
is reused each time some bytes are read.
The default value is 300 seconds.
ef.download.stream.sleep.time.data
Specifies sleep time, in milliseconds, between two consecutive data reads when data is available.
It is only used by the remote download manager.
The default value is 750 milliseconds.
ef.download.read.buffer.size
Sets buffer size used to read bytes from file.
The default value is 8192 bytes.
ef.download.write.buffer.size
Sets buffer size used to write bytes back to browser.
The default value is the system one.
ef.allow.hidden.file.download
Enables downloading hidden files. It is only used by the local download manager.
The default value is false.
EF_AGENT_HOST
Specifies default agent host.
The default value is localhost (or install time value).
EF_AGENT_PORT
Specifies where default agent listens.
The default value is 9999 (or install time value).
EF_DEFAULT_AUTHORITY
Specifies authority used to authenticate users. It can be a list of comma (,) separated values. The
first authority is used to authenticate, the others grant user access to resources protected by those
authorities without requiring further credentials.
The default value is chosen at install time.
EnginFrame Administrator's Reference
7
server.conf
EF_ROOT_CONTEXT
Specifies URI used to access EnginFrame Portal.
The default value is enginframe (or install time value).
EF_LICENSE_PATH
Specifies absolute path to EnginFrame's license.
authorization.alias.bin
Specifies bin directory that must be used by the authority alias (where alias should be substituted
with the name of an authentication system). The alias defined in this section can be used in the
EnginFrame Service Definition Files. The aliases included with EnginFrame are: activedirectory,
http, ldap, os, pam.
The default value for the os is EF_ROOT/plugins/os/bin. This value should not be
changed.
authorization.alias.login
Specifies login file that must be used by this authority. The alias defined in this section can be
used in the EnginFrame Service Definition Files. The aliases included with EnginFrame are:
activedirectory, http, ldap, os, pam.
The login file must be a well-formed XML document. Its structure is described in Chapter 5,
EnginFrame Authentication XML.
The default value for the os is EF_ROOT/plugins/os/etc/os.login.
EF_KEY_STORE
Specifies server's keystore containing its certificates. An absolute pathname must be used.
EnginFrame uses this parameter only if the server is using RMI over SSL to communicate with
at least one agent.
EF_KEY_STORE_PASSWORD
Specifies server's keystore password. It defaults to changeit. EnginFrame uses this parameter
only if the server is using RMI over SSL to communicate with at least one agent.
EF_KEY_STORE_TYPE
Specifies server's keystore type. The valid values are JKS and PKCS12. By default the JKS type
is used so this parameter must be set only if a PKCS12 keystore is used. EnginFrame uses this
parameter only if the server is using RMI over SSL to communicate with at least one agent.
EF_KEY_STORE_ALGORITHM
Specifies server's keystore X509 algorithm. This defaults to the JVM default algorithm. For Sun's
implementation, the default is SunX509. For IBM JVMs you should use the value IbmX509.
For other vendors, consult the JVM documentation for the correct value. EnginFrame uses this
parameter only if the server is using RMI over SSL to communicate with at least one agent.
EF_KEY_ALIAS
Specifies server's certificate private key alias. Use this parameter if your have more than one
key in the keystore. If the parameter is not set, the first key read in the keystore will be used.
EnginFrame uses this parameter only if the server is using RMI over SSL to communicate with
at least one agent.
EF_TRUST_STORE
Specifies server's truststore file. An absolute pathname must be used. EnginFrame uses this
parameter only if the server is using RMI over SSL to communicate with at least one agent.
8
EnginFrame Administrator's Reference
mime-types.xml
EF_TRUST_STORE_PASSWORD
Specifies server's truststore password. It defaults to changeit. EnginFrame uses this parameter
only if the server is using RMI over SSL to communicate with at least one agent.
EF_TRUST_STORE_TYPE
Specifies server's truststore type. The valid values are JKS and PKCS12. By default the JKS type
is used so this parameter must be set only if a PKCS12 truststore is used. EnginFrame uses this
parameter only if the server is using RMI over SSL to communicate with at least one agent.
EF_TRUST_STORE_ALGORITHM
Specifies server's truststore X509 algorithm. This defaults to the JVM default algorithm. For Sun's
implementation, the default is SunX509. For IBM JVMs you should use the value IbmX509.
For other vendors, consult the JVM documentation for the correct value. EnginFrame uses this
parameter only if the server is using RMI over SSL to communicate with at least one agent.
EF_DEFAULT_GRID_SDF
Specifies default grid manager SDF.
Important
This variable has been deprecated since EnginFrame 2010; plugins should
use the unified grid plugin services including EF_ROOT/plugins/
grid/WEBAPP/lib/xml/com.enginframe.grid.xml.
ef.charts.base.url
Specifies charts provider base URL. You can use the internal charts provider or any external
service compatible with Google Chart API. For instance, to use the public Google Chart service,
set this parameter to http://chart.apis.google.com/chart. If this parameter is not
specified or left empty, the internal chart provider is used.
The default value is /${EF_ROOT_CONTEXT}/efcharts.
EF_ADMIN
Specifies EnginFrame administrator. This user cannot be root. You can specify more than one
value (each corresponding to an existing user of your system) by separating the values using a
comma (,).
EF_HTTP_AUTHENTICATION
Specifies if EnginFrame should trust HTTP authentication arriving from the web server. The
default value is false. If you want to use web server authentication, put this value to true.
mime-types.xml
This file adds extra mime types to EnginFrame Server settings. The EnginFrame Download Servlet
guesses a file's content type using JVM built-in mime types. If the JVM does not know a mime type for
a certain file extension, the EnginFrame Server queries its mime type extensions to guess the content
type. This file belongs to root for security reasons. This file allows root to add extra mime types to
EnginFrame without modifying the JAVA_HOME/jre/lib/content-types.properties
file, which would be shared by all applications using the ame JVM. The following is the file shipped
by EnginFrame:
EnginFrame Administrator's Reference
9
mime-types.xml
<ef:mime-types xmlns:ef="http://www.enginframe.com/2000/EnginFrame">
<ef:mime-type>
<ef:type type="text/plain"/>
<ef:desc desc="ASCII Text File"/>
<ef:extensions>
<ef:extension ext=".log"/>
</ef:extensions>
<ef:match-list>
<ef:match expr="[A-Z0-9]*.ef" />
<!-Other accepted attributes:
1) multiline="true|false"
2) singleline="true|false"
-->
<ef:match expr="README" casesensitive="false" />
</ef:match-list>
</ef:mime-type>
<ef:mime-type>
<ef:type type="application/x-javascript"/>
<ef:desc desc="JavaScript File"/>
<ef:match-list>
<ef:match expr="^.*[Jj][Ss]" />
</ef:match-list>
</ef:mime-type>
<ef:mime-type>
<ef:type type="text/css"/>
<ef:desc desc="CSS File"/>
<ef:match-list>
<ef:match expr="^.*[Cc][Ss][Ss]" />
</ef:match-list>
</ef:mime-type>
<ef:mime-type>
<ef:type type="application/xml"/>
<ef:desc desc="XML file"/>
<ef:match-list>
<ef:match expr="^.*[Xx][Bb][Ll]" />
</ef:match-list>
</ef:mime-type>
<ef:mime-type>
<ef:type type="image/vnd.microsoft.icon"/>
<ef:desc desc="ICO File"/>
<ef:match-list>
<ef:match expr="^.*[Ii][Cc][Oo]" />
</ef:match-list>
</ef:mime-type>
</ef:mime-types>
EnginFrame Server tries to associate a mime type to a selected file. If it cannot associate a mime
type, it asks the JVM to associate a mime type. If both lookup fail, the default mime type (if it exists)
10
EnginFrame Administrator's Reference
mime-types.xml
is associated. This is very useful for adding file extensions/mime types that are not very common
and that do not need to be added to the global JVM content type configuration file. EnginFrame
dynamically reloads this file once it has been modified, so there is no need to restart your Web Server
in order to see changes.
The ef:extensions section contains exact matches. Thus, in this example, any file that ends with
.log extension has text/plain mime type. The ef:match-list section contains regular expressions
for matching a file name. Thus, in this example, license.ef or README have text/plain mime type;
whilst readme has an UNKNOWN mime type. And the file functions.js has application/x-javascript
mime type.
The ef:mime-types has another child tag, ef:default. This tag specifies the default mime
type for all those cases where a match was not found.
The syntax is <ef:default type="expected_mime_type" />.
Important
Be careful when setting ef:default tag since all files that cannot be
mapped neither by EnginFrame nor by JVM are associated to that mime-type.
EnginFrame Administrator's Reference
11
3
Agent Configuration
The EnginFrame Agent configuration file is:
• EF_ROOT/conf/agent.conf
EnginFrame Agents can run either with the privileges of a regular Unix user or with the privileges of
the super-user (root). Super-user privileges are only used, on behalf of an authenticated user, to:
1. Manage an EnginFrame spooler directory that is owned by the authenticated user.
2. Run an EnginFrame service with the privileges of the authenticated user. Furthermore, the root
user is not accepted as an EnginFrame authenticated user and any attempt of run a service with
root privileges fails.
agent.conf
Here follows a description of the parameters and how to use them.
ef.agent.port
Specifies port on which EnginFrame Server contacts EnginFrame Agent. The default value is
9999.
If another process is using this port, or if you want to change the port number, be sure to
change port attribute of the <ef:location> tag in your Service Definition Files and/or the
EF_AGENT_PORT value defined in the server conf file; it should be consistent with the new
setting.
ef.agent.bind.port
Optional value defining where RMI bound objects are listening. If EnginFrame Agent is behind
a firewall then you must this value. The default value is 9998.
ef.output.limit
Specifies maximum number of bytes an output process can return. Output stream is truncated if
this limit is exceeded.
The default value is 1 MB.
ef.switch.user.params
Specifies parameters passed to the Unix su command when executing user service.
EnginFrame Administrator's Reference
13
agent.conf
Parameters are appended just after "su" invocation before username part:
$su [params] <username> -c ...
Multiple parameters separated by a space can be specified in the option without using quotes or
double quotes,
e.g. ef.switch.user.params=-f -m
If it is set with an empty string, no parameters will be passed to the su command.
The default value is "-" meaning the user's profile settings will be loaded during switching
operation.
ef.download.server.url
Specifies destination URL where EnginFrame Agent contacts EnginFrame Server to send the
download responses. It is only used by remote download manager.
ef.download.server.url contains the HTTP/HTTPS URL for contacting the
EnginFrame Server.
EnginFrame Server download URL is in the form of
http[s]://<host>:<port>/<EF web context>/download
E.g. http://localhost:8080/enginframe/download (EnginFrame Server and
EnginFrame Agent on the same host)
ef.download.read.buffer.size
Sets buffer size used to read bytes from file.
The default value is 8192 bytes.
ef.download.write.buffer.size
Sets buffer size used to write bytes back to EnginFrame Server.
The default value is the system one.
ef.download.socket.buffer.size
Sets socket send buffer size when connecting to EnginFrame Server.
The default value is the system one.
authorization.alias.bin
Specifies directory where alias authority can find executable files used to authenticate users.
By default, EnginFrame includes the os (operating system) context. This context uses the
directory EF_ROOT/plugins/os/bin to store its binary files. This value should not be
changed.
If you define your own contexts and they need some external program to authenticate users, you
can set the related binary directory using this option.
authorization.alias.runAsUser
Specifies on behalf of which user to execute the authentication service for the alias authority.
This is used if EnginFrame Agent runs as root.
14
EnginFrame Administrator's Reference
agent.conf
It can assume the following values:
• ‘*’ to run the services as the user being authenticated
• ‘username’ to run the services as username user
Note
It is not possible to run the services as root user.
By default, authentication services are executed as EF_ADMIN user.
EF_RMI_OVER_SSL
Set to true to use the RMI over SSL protocol for the communications between EnginFrame
Server and EnginFrame Agent.
EF_KEY_STORE
Specifies agent's keystore containing its certificates. An absolute pathname must be used.
EnginFrame uses this parameter only if the EF_RMI_OVER_SSL parameter is set to true.
EF_KEY_STORE_PASSWORD
Specifies agent's keystore password. It defaults to changeit. EnginFrame uses this parameter
only if the EF_RMI_OVER_SSL parameter is set to true.
EF_KEY_STORE_TYPE
Specifies agent's keystore type. The valid values are JKS and PKCS12. By default the JKS type
is used so this parameter must be set only if a PKCS12 keystore is used. EnginFrame uses this
parameter only if EF_RMI_OVER_SSL parameter is set to true.
EF_KEY_STORE_ALGORITHM
Specifies agent's keystore X509 algorithm. This defaults to the JVM default algorithm. For Sun's
implementation, the default is SunX509. For IBM JVMs you should use the value IbmX509.
For other vendors, consult the JVM documentation for the correct value. EnginFrame uses this
parameter only if EF_RMI_OVER_SSL parameter is set to true.
EF_KEY_ALIAS
Specifies agent's certificate private key alias. Use this parameter if your have more than one
key in the keystore. If the parameter is not set, the first key read in the keystore will be used.
EnginFrame uses this parameter only if EF_RMI_OVER_SSL parameter is set totrue.
EF_TRUST_STORE
Specifies the agent's truststore file. An absolute pathname must be used. EnginFrame uses this
parameter only if EF_RMI_OVER_SSL parameter is set to true.
EF_TRUST_STORE_PASSWORD
Specifies agent's truststore password. It defaults to changeit. EnginFrame uses this parameter
only if EF_RMI_OVER_SSL parameter is set to true.
EF_TRUST_STORE_TYPE
Specifies agent's truststore type. The valid values are JKS and PKCS12. By default the JKS type
is used so this parameter must be set only if a PKCS12 truststore is used. EnginFrame uses this
parameter only if EF_RMI_OVER_SSL parameter is set to true.
EnginFrame Administrator's Reference
15
agent.conf
EF_TRUST_STORE_TYPE
Specifies agent's truststore X509 algorithm. This defaults to the JVM default algorithm. For Sun's
implementation, the default is SunX509. For IBM JVMs you should use the value IbmX509.
For other vendors, consult the JVM documentation for the correct value. EnginFrame uses this
parameter only if EF_RMI_OVER_SSL parameter is set to true.
EF_ADMIN
Specifies EnginFrame administrator. This user cannot be the root user. You can specify more
than one value (each corresponding to an existing user of your system) by separating the values
using a comma (,).
16
EnginFrame Administrator's Reference
ef_java.policy
ef_java.policy
This file is used by the JVM that starts EnginFrame Agent daemons. It grants the Java permissions
needed by agent daemon classes and by the classes arriving from the EnginFrame Servers via RMI
calls. The installed Java RMI Security Manager disallows invoking methods on the agent host unless
they have been granted permissions in this file.
EF_JAVA.POLICY
The main entries contained in this file are:
// The Agent classes have ALL permissions.
grant codeBase "file:EF_ROOT/agent/*" {
permission java.security.AllPermission;
};
// Grants for the CORE classes.
grant SignedBy NICE {
permission java.security.AllPermission;
};
The first grant reserves all permissions to the classes contained in agent daemon startup directory;
while the second grant reserves all permissions to EnginFrame classes arriving from anywhere
(Intra/Inter-Net) as long as these classes are signed by NICE's certificate.
These grants are the default ones installed by EnginFrame at setup time. Agent daemons use the
EF_ROOT/conf/.keystore as Java key store. This file must not be removed or tampered
since it contains NICE's certificate public keys used to verify classes arriving over the wire.
This policy file also contains the default entries found in the java.policy file installed with any
JVM.
Once you edit this policy file, you have to restart EnginFrame Agent daemons by issuing
$NICE_ROOT/bin/enginframe agent start
EnginFrame Administrator's Reference
17
4
Logging Configuration
EnginFrame’s logging engine reads a configuration parameter that allows changing the underlying
logging toolkit. The supported toolkits there are:
• Apache Log4J
• Apache Avalon Logkit
EnginFrame decided for Logkit since it is widely used and since it is a toolkit focused on speed,
reliability and dynamic reconfiguration. The next sections describe how to configure the underlying
Logkit implementation.
Priorities
One of the advantages of a logging toolkit is fine grain control over which statements get printed.
At some times during development you may wish to enable all logging statements and at other times
they may wish to disable debug messages. It was from this need that the notion of Priorities was
born. A Priority describes the criticalness of a LogEvent. Below is a list of priorities that are usable
within the LogKit system:
• NONE: No messages are emitted.
• DEBUG: Developer oriented messages, usually used during development of the product.
• INFO: Useful information messages such as state changes, client connection, user login etc.
• WARN: A problem or conflict has occurred but it may be recoverable, then again it could be the
start of the system failing.
• ERROR: A problem has occurred but it is not fatal. The system still functions.
• FATAL_ERROR: Something caused whole system to fail. This indicates that an administrator
should restart the system and try to fix the problem that caused the failure.
Each logger instance is associated with a Priority. This allows you to limit each logger so that it only
displays messages greater than a certain priority. So if a DEBUG message occurred and the logger's
priority was WARN, the LogEvent would be suppressed.
EnginFrame Administrator's Reference
19
Categories
Categories
In a complex system it is often not enough to suppress logging based on priority. For instance you
may wish to log the network subsystem with DEBUG priority while the simulator subsystem with
WARN priority. To accomplish this LogKit uses a concept termed Categories.
Each category is a name, made up of name components separated by a ".". So a category named
"network.interceptor.connected" is made up of three name components "network", "interceptor" and
"connected", ordered from left to right. Every logger is associated with a category at creation.
LogKit takes it one step further and assumes that the namespace is hierarchical. The left-most name
component is the most generic category while the right-most name component is the most specific.
So "network.interceptor.connected" is a child category of "network.interceptor", which is in turn a
child category of "network". There is also a root category "" that is hidden.
The main reason for structuring logging namespace in a hierarchical manner is to allow inheritance.
A logger will inherit its parent priority if it has not been explicitly set. This allows you to set the
"network" logger to have INFO priority and unless the "network.interceptor" has had it's priority set
it will inherit the INFO priority.
Log Targets
In LogKit, LogTargets are the destination of LogEvents. Decoupling LogEvent generation from
handling allows developers to change destinations of LogEvents dynamically or via configuration
files. Possible destinations include writing to a database, a file, an IRC channel, a syslog server, an
instant messaging client, etc.
Formatters
LogTargets that write to a serial or unstructured store (i.e., file-system or network based LogTargets)
need some method to serialize the LogEvent before writing to the store. The most common way to
serialize the LogEvent is to use a Formatter.
The format specified consists of a string containing raw text combined with pattern elements. Each
pattern element has the generalized form
%[+|-]#.#{field:subformat}
• +|- indicates whether the pattern element should be left or right justified (defaults to left justified
if unspecified).
• #.# indicates the minimum and maximum size of output, if unspecified the output is neither padded
nor truncated.
• field indicates the field to be written and must be one of category, context, user, message, time,
rtime (time relative to start of application), throwable or priority. This parameter must be supplied
and correlates to fields of LogEvent.
• subformat is currently used except when field is context or time field. This is further discussed
below.
A number of examples for EnginFrameLogFormatter's format and actual output follows.
20
EnginFrame Administrator's Reference
Formatters
format: "%7.7{priority} %5.5{rtime} [%8.8{category}]:%{message}\n%{throwable}"
output:
DEBUG 123 [network.]: This is a debug message
format: "%7.7{priority} %5.5{rtime} [%{category}]:%{message}\n"
output:
DEBUG 123 [network.interceptor.connected]: This is a debug message
DEBUG 123 [network]: This is another debug message
format: "%7.7{priority} %5.5{rtime} [%10.{category}]:%{message}\n"
output:
DEBUG 123 [network.interceptor.connected]: This is a debug message
DEBUG 123 [network ]: This is another debug message
Example 4.1.
EnginFrame Administrator's Reference
21
log.agent.xconf
log.agent.xconf
Here follows the default Agent logging configuration file:
<?xml version="1.0"?>
<logkit>
<factories>
<factory type="enginframe"
class="com.enginframe.common.utils.log.EnginFrameTargetFactory" />
</factories>
<targets>
<enginframe id="agent.remote">
<filename>${EF_LOGDIR}/agent.remote.log</filename>
<format type="enginframe">
%{time:yyy/MMM/dd HH:mm.ss} %7.12{priority}
TID[%{tid}] %{user} %{class:short}.%{method:short}:
%{message}\n%{throwable}
</format>
<!-append=false: will override existing log files on startup
append=true: will append to the existing log files
-->
<append>true</append>
<!-rotation: allows you to rotate log files one they
meet certain criteria. In example below,
files are rotated once they
are bigger than 10 Mb.
-->
<rotation type="revolving" max="4">
<size>10m</size>
</rotation>
</enginframe>
</targets>
<categories>
<!-log-level: One of DEBUG, INFO, WARN, ERROR, FATAL_ERROR, NONE.
Log level could be different for every category and subcategory.
Not all subcategories are defined in this file. Not
defined subcategories will be created automatically
inheriting settings of the parent subcategory.
When defining subcategory manually, it is required to
specify log targets, because they are not inherited in
this case.
-->
<category name="" log-level="WARN">
<log-target id-ref="agent.remote"/>
</category>
<category name="com.enginframe.agent.DefaultAgentCreator"
log-level="INFO">
<log-target id-ref="agent.remote"/>
</category>
</categories>
</logkit>
22
EnginFrame Administrator's Reference
log.server.xconf
This file says that Logkit has to create a Log Target named agent.remote. This target writes into the
EF_LOGDIR/agent.remote.log file. Messages are appended to existing files. Log files are rotated
for a maximum of four times and for a maximum of ten megabyte of data.
Most categories have WARN as priority level and write to agent.remote log targets.
log.server.xconf
Here follows the default Server logging configuration file:
<?xml version="1.0"?>
<logkit>
<factories>
<factory type="enginframe"
class="com.enginframe.common.utils.log.EnginFrameTargetFactory" />
</factories>
<targets>
<enginframe id="core">
<filename>${EF_LOGDIR}/ef.log</filename>
<format type="enginframe">
%{time:yyy/MMM/dd HH:mm.ss} %7.12{priority}
TID[%{tid}] %{user} %{class:short}.%{method:short}:
%{message}\n%{throwable}
</format>
<!-append=false: will override existing log files on startup
append=true: will append to the existing log files
-->
<append>true</append>
<!-rotation: allows you to rotate log files one they
meet certain criteria. In example below,
files are rotated once they are bigger than 10 Mb.
-->
<rotation type="revolving" max="4">
<size>10m</size>
</rotation>
</enginframe>
</targets>
EnginFrame Administrator's Reference
23
log.server.xconf
<categories>
<!-log-level: One of DEBUG, INFO, WARN, ERROR, FATAL_ERROR, NONE.
Log level could be different for every category and subcategory.
Not all subcategories are defined in this file. Not
defined subcategories will be created automatically
inheriting settings of the parent subcategory.
When defining subcategory manually, it is required to
specify log targets, because they are not
inherited in this case.
-->
<category name="" log-level="WARN">
<log-target id-ref="core" />
</category>
<category name="com.enginframe.server.webservices" log-level="WARN">
<log-target id-ref="core" />
</category>
<category name="org.apache.axis" log-level="WARN">
<category name="i18n" log-level="NONE">
<log-target id-ref="core" />
</category>
<category name="utils" log-level="NONE">
<log-target id-ref="core" />
</category>
<log-target id-ref="core" />
</category>
</categories>
</logkit>
This file says that Logkit has to create a Log Target named core . This target writes into the
EF_LOGDIR/ef.log file. Messages are appended to existing files. Log files are rotated for a maximum
of four times and for a maximum of ten megabyte of data.
All categories have WARN as priority level and write to core log targets when EnginFrame core
classes write messages. The categories that have NONE do not write messages.
24
EnginFrame Administrator's Reference
Configuration Examples
Configuration Examples
This section describes how to modify EnginFrame logging configuration files and change logging
behaviour. When any of the EnginFrame logging configurations is modified, changes are quickly
propagated without restarting daemons.
<filename>EF_LOGDIR/my.file.log</filename>
Example 4.2. Change log file destination
<rotation type="revolving" max="7">
<size>1m</size>
</rotation>
Example 4.3. Change maximum number of rotation files
<rotation type="revolving" max="4">
<size>15m</size>
</rotation>
Example 4.4. Change log file size
<category name="com.enginframe" log-level="DEBUG">
<category name="authentication" log-level="INFO">
<log-target id-ref="core"/>
</category>
[…]
</category>
Example 4.5. Change priority for nested category
EnginFrame Administrator's Reference
25
5
EnginFrame Authentication XML
Login Tags
This section explains EnginFrame's authentication XML used to grant access to its system.
<ef:command>
This tag represents a command that failed.
Its text node value is the command that failed.
The following attribute could be specified:
Table 5.1. <ef:command> tag attributes
Name
Required?
Notes
errorLevel
Optional
Specifies the exit code of the command that failed.
This tag does not have children nodes.
It can only be contained, optionally, into an <ef:error> tag.
Examples:
• An application error command
<ef:error-group>
<ef:error type="system">
[...]
</ef:error>
<ef:error type="application">
<ef:title>LSF Integration Error</ef:title>
<ef:command>EF_ROOT/plguins/lsf/bin/bsub</ef:command>
<ef:message>
The LSF environment is not correctly set.
</ef:message>
</ef:error>
</ef:error-group>
Example 5.1. An application error command
• An authentication error command with error level specified
EnginFrame Administrator's Reference
27
<ef:error>
[...]
<ef:error type="auth">
<ef:title>EnginFrame Authentication Error</ef:title>
<ef:command errorLevel="127">
EF_ROOT/plguins/ef/bin/ef.auth
</ef:command>
<ef:message>
The authentication process failed, the username or password is wrong.
</ef:message>
</ef:error>
[...]
Example 5.2. An authentication error command with error level specified
<ef:error>
This tag represents an error that occurred inside EnginFrame. The error could occur anywhere: during
authentication, executing an application, etc.
Its text node child is ignored.
The following attributes must be specified:
Table 5.2. <ef:error> tag attributes
Name
Required?
Notes
type
Required
Defines what kind of error occurred.
This node could contains the following children elements:
Table 5.3. <ef:error> child elements
Name
Required?
Notes
<ef:title>
Optional
Gives the title to the error section.
<ef:command>
Optional
The command that failed.
<ef:message>
Optional
Describes what happened.
Examples:
• An application error inside an error-group
<ef:error-group>
<ef:error type="system">
[...]
</ef:error>
<ef:error type="application">
<ef:title>LSF Integration Error</ef:title>
<ef:command>EF_ROOT/plugins/lsf/bin/bsub</ef:command>
<ef:message>
The LSF environment is not correctly set.
</ef:message>
</ef:error>
</ef:error-group>
Example 5.3. An application error inside an error-group
28
EnginFrame Administrator's Reference
<ef:login>
• An authentication error
[...]
<ef:error type="auth">
<ef:title>EnginFrame Authentication Error</ef:title>
<ef:command>EF_ROOT/plugins/ef/bin/ef.auth</ef:command>
<ef:message>
The authentication process failed, the username or password is wrong.
</ef:message>
</ef:error>
[...]
Example 5.4. An authentication error
<ef:login>
This tag defines the login credentials needed by the authentication plugin.
Its text node child is ignored.
The following attributes may be specified:
Table 5.4. <ef:login> tag attributes
Name
Required?
Notes
title
Required
Specifies the login title which appears upon
the widgets. This helps users know what their
credentials are needed for.
It must contain the following child element:
Table 5.5. <ef:login> child elements
Name
Required?
<ef:signature> Required
Notes
Declares which kind of widgets are to be displayed.
It also declares the names of the widgets.
Examples:
• OS login example
<ef:login title="Login to the Operating System">
<ef:signature label="Username:"
type="text"
id="_username"/>
<ef:signature label="Password:"
type="password"
id="_password"/>
</ef:login>
Example 5.5. OS login example
EnginFrame Administrator's Reference
29
<ef:message>
<ef:message>
This tag represents an error message explaining what went wrong.
Its text node value is the error message.
This tag does not have attributes nor children nodes.
It can only be contained, optionally, into an <ef:error> tag.
Examples:
• An application error message
<ef:error-group>
<ef:error type="system">
[...]
</ef:error>
<ef:error type="application">
<ef:title>LSF Integration Error</ef:title>
<ef:command>EF_ROOT/plguins/lsf/bin/bsub</ef:command>
<ef:message>
The LSF environment is not correctly set.
</ef:message>
</ef:error>
</ef:error-group>
Example 5.6. An application error message
• An authentication error message
[...]
<ef:error type="auth">
<ef:title>EnginFrame Authentication Error</ef:title>
<ef:command
EF_ROOT/plguins/ef/bin/ef.auth
</ef:command>
<ef:message>
The authentication process failed, the username or password is wrong.
</ef:message>
</ef:error>
[...]
Example 5.7. An authentication error message
<ef:signature>
Used in the <ef:login> tag, it defines the login widgets which are shown to users. It also defines
the name of the widgets, the labels of the widgets, and the values passed to EnginFrame
Its text node child is ignored.
The following attributes may be specified:
Table 5.6. <ef:signature> tag attributes
30
Name
Required?
Notes
label
Required
Specifies the label of the widget.
EnginFrame Administrator's Reference
<ef:title>
Name
Required?
Notes
type
Required
Identifies the widget type. The same types
supported by <ef:option>can be used here.
id
Required
Specifies the name that will be used by the
authenticating method to get the widget's value.
These values are reserved keywords used by
EnginFrame: _username and _password.
value
Optional
Specifies a default value for the widget.
It does not contain sub-tags.
Examples:
• OS signature example
<ef:login title="Login to the Operating System">
<ef:signature label="Username:"
type="text"
id="_username"/>
<ef:signature label="Password:"
type="password"
id="_password"/>
<ef:signature label="Domain:"
type="hidden"
id="_domain"
value="enginframe.com"/>
</ef:login>
Example 5.8. OS signature example
<ef:title>
This tag represents an error section title.
Its text node value is the error section title.
This tag does not have attributes nor children nodes.
This tag can only be, optionally, contained in an <ef:error> tag.
Examples:
• An application error title
EnginFrame Administrator's Reference
31
<ef:title>
<ef:error-group>
<ef:error type="system">
[...]
</ef:error>
<ef:error type="application">
<ef:title>LSF Integration Error</ef:title>
<ef:command>EF_ROOT/plguins/lsf/bin/bsub</ef:command>
<ef:message>
The LSF environment is not correctly set.
</ef:message>
</ef:error>
</ef:error-group>
Example 5.9. An application error title
• An authentication error title
[...]
<ef:error type="auth">
<ef:title>EnginFrame Authentication Error</ef:title>
<ef:command>EF_ROOT/plugins/ef/bin/ef.auth</ef:command>
<ef:message>
The authentication process failed, the username or password is wrong.
</ef:message>
</ef:error>
[...]
Example 5.10. An authentication error title
32
EnginFrame Administrator's Reference
6
Authorization System Configuration
This chapter describes EnginFrame's authorization system configuration. In a general view an
authorization system is aimed to authorize user accesses to resources allowing or denying operations
according to a set of predefined policies.
EnginFrame authorization system framework describes users as Actors, resources as SDF folders,
services, service options, service actions, and output, while policies where permissions are defined
are Access Control Lists (ACL).
The whole authorization framework defines who can do what on which resources. By configuring
the authorization system, it is possible to give different views of EnginFrame Portal to different users
and groups of users.
authorization.xconf
The authorization system configuration file is:
• EF_ROOT/conf/authorization.xconf
Configurations are set up by EnginFrame Server and are dynamically re-loaded once this file is
modified.
The file authorization.xconf is an XML file built up of two sections:
• Actors section introduced with the tag <ef:acl-actor-list>
• Access Control Lists section with the tag <ef:acl-list>
EnginFrame Administrator's Reference
33
authorization.xconf
Here follows the high level structure of the authorization.xconf file:
<ef:authorization>
<!-- EnginFrame Authorization Actors section -->
<ef:acl-actor-list>
...
</ef:acl-actor-list>
<!-- EnginFrame Authorization ACL section -->
<ef:acl-list>
...
</ef:acl-list>
</ef:authorization>
and now follows an example:
...
<!-- EnginFrame Authorization Actors section -->
<ef:acl-actor-list>
<!-- Actor made up of two simple users and two Actors -->
<ef:acl-actor id="nice" type="efgroup">
<ef:info>NICE people</ef:info>
<ef:acl-member type="efuser">andrea</ef:acl-member>
<ef:acl-member type="efuser">beppe</ef:acl-member>
<ef:acl-member type="acl-actor">developers</ef:acl-member>
<ef:acl-member type="acl-actor">efadmin</ef:acl-member>
</ef:acl-actor>
<ef:acl-actor id="developers" type="efgroup">
<ef:info>EnginFrame Developers</ef:info>
<ef:acl-member type="efuser">antonio</ef:acl-member>
<ef:acl-member type="efuser">mauri</ef:acl-member>
<ef:acl-member type="acl-actor">goldrake</ef:acl-member>
</ef:acl-actor>
<!-Members of this Actor are dynamically loaded from the
operating system group “admins”
-->
<ef:acl-actor id="admins" type="osgroup"/>
</ef:acl-actor-list>
...
Example 6.1. An Actors section example
34
EnginFrame Administrator's Reference
authorization.xconf
The definition of an ACL adheres to this XML structure:
<ef:acl id="unique_id”>
<ef:acl-priority>allow | deny</ef:acl-priority>
<ef:acl-allow>
<ef:actor id=”actor_id”>
<ef:action-list>
<ef:read/>
<ef:execute/>
...
</ef:action-list>
</ef:actor>
</ef:acl-allow>
<ef:acl-deny>
<ef:actor id=”actor_id”>
<ef:action-list>
<ef:read/>
<ef:execute/>
...
</ef:action-list>
</ef:actor>
</ef:acl-deny>
</ef:acl>
another ACL snippet follows:
<ef:acl-list>
...
<ef:acl id="priv-exec">
<ef:info>Privileged permissions for Admins</ef:info>
<ef:acl-priority>deny</ef:acl-priority>
<ef:acl-allow>
<ef:actor id="efadmin">
<ef:action-list>
<ef:read/>
<ef:write/>
<ef:execute/>
<ef:delete/>
</ef:action-list>
</ef:actor>
</ef:acl-allow>
</ef:acl>
...
</ef:acl-list>
Example 6.2. Example ACL definition
EnginFrame Administrator's Reference
35
Condition Based ACL
Condition Based ACL
An ACL could have some extra conditions that have to be met in order to grant access to a resource.
EnginFrame allows to define these conditions using logical operators: or, and, not, and equals.
The next example defines an ACL snippet. Let's explain each element:
<!-- EnginFrame Authorization ACL section -->
<ef:acl-list>
...
<ef:acl id="project-acme">
<ef:info>
Privileged permissions for Project ACME
</ef:info>
<ef:acl-priority>deny</ef:acl-priority>
<ef:acl-allow>
<ef:actor id="company-users">
<ef:condition>
<ef:or>
<ef:and>
<ef:equals type=”session”
id=”project”
value=”acme”
casesensitive=”true” />
<ef:equals type=”session”
id=”${project}_responsible”
value=”true”
casesensitive=”false” />
</ef:and>
<ef:and>
<ef:equals type=”session”
id=”administrator”
value=”true”
casesensitive=”false”/>
<ef:not>
<ef:equals type=”property”
id=”${EF_USER}”
value=”jack”
casesensitive=”true” />
</ef:not>
</ef:and>
</ef:or>
</ef:condition>
<ef:action-list>
<ef:read/>
<ef:write/>
<ef:execute/>
<ef:delete/>
</ef:action-list>
</ef:actor>
</ef:acl-allow>
</ef:acl>
...
</ef:acl-list>
Example 6.3. ACL snippet including conditionals
The resources guarded by ACL "project-acme" are accessible if all following requirements are
met:
36
EnginFrame Administrator's Reference
Condition Based ACL
• Current user belongs to "company-users".
• and one of the following is true:
• Current user has a session variable named "project" and its value is exactly "acme".
• Current user has a session variable named "acme_responsible" and its value is "true"
independently from case of letters.
or
• Current user has a session variable named "administrator" and its value is "true"
independently from case of letters.
• Current user is not named "jack".
The ef:or tag is a condition container and behaves as a logical or. It evaluates its child conditions
until one results true.
The ef:and tag is a condition container and behaves as a logical and. It evaluates all its child
conditions and results true only if they are all true.
The ef:not tag contains only one condition. It negates the result of its child condition evaluation.
The ef:equals tag checks two arguments for equality. The arguments to check are defined by the
type attribute and the id attribute; the value attribute must be matched depending on casesensitive
attribute.
The id attribute meaning varies depending on the type attribute:
• session, used to pick user session variable
• property, used to pick EnginFrame system property
• xpath, used to apply XPath expression on current DOM
<ef:equals type=”session”
id=”administrator”
value=”true”
casesensitive=”false” />
Example 6.4. Session ‘type’ equals tag
Used to pick session variable named administrator and whose value must be true (without bothering
for case.)
<ef:equals type=”property”
id=”${EF_USER}”
value=”mary”
casesensitive=”true” />
Example 6.5. Property ‘type’ equals tag
Used to pick EnginFrame system property named ${EF_USER} and whose value must be exactly
mary. Since it is a dynamic variable it is expanded to user currently browsing the portal.
EnginFrame Administrator's Reference
37
Condition Based ACL
EnginFrame system properties are those
• Loaded by the JVM
• Passed to JVM via command line (i.e., using –Dname=value)
• Loaded in EnginFrame configuration files
<ef:equals type=”xpath”
id=”starts-with(//ef:profile/ef:user/., ‘br’)”
value=”true”
casesensitive=”true” />
Example 6.6. XPath ‘type’ equals tag
Used to pick from current DOM XPath //ef:profile/ef:user/text() and whose value
must exactly start with br.
38
EnginFrame Administrator's Reference
7
HTTP Basic Authentication
Configuration
You can use HTTP Basic Authentication to protect your EnginFrame Portal. This can be useful
when the Tomcat Web Server is behind an Apache Web Server that already uses HTTP Basic
Authentication.
The next sections describe how to enable HTTP Basic Authentication to protect EnginFrame Portal
for the following scenarios:
• Using Tomcat as Web Server
• Using an existing Apache + Tomcat (reuse Apache credentials)
The Java 2 Enterprise Edition (J2EE) standard allows you to protect your EnginFrame Portal
independently from the authority source used behind the scenes. Three different authority sources
are described:
• EnginFrame digested username/password file database
• Apache digested username/password file database
• LDAP Server database
Add the following in your EnginFrame Portal configuration files to use these authority sources:
• Add a <security-constraint> in your web.xml file (not when your using credentials in
Apache's database.)
• Add a <login-config> in your web.xml file (not when your using credentials in Apache's
database.)
• Set EF_HTTP_AUTHENTICATION=true in your server.conf file.
EnginFrame Administrator's Reference
39
Protecting the EnginFrame Web
Application
Protecting the EnginFrame Web Application
First of all, you have to protect the EnginFrame Web Application according to J2EE specifications.
Adhering to the J2EE specifications, you have to modify the EnginFrame Portal web deployment
descriptor EF_ROOT/WEBAPP/WEB-INF/web.xml by adding security and login tags. This file
is validated by a DTD so tags have to be placed in the correct position. The complete J2EE DTD
can be found at:
http://java.sun.com/dtd/web-app_2_3.dtd
If you chose http authority during EnginFrame installation, then the installer already added the
security constraints and the login configuration. If you did not choose http at install time or you need
to modify the security configuration, then edit the EF_ROOT/WEBAPP/WEBINF/web.xml. Add
the following tags after the </welcome-file-list> tag and before the </web-app> tag:
<security-constraint>
<web-resource-collection>
<web-resource-name>EnginFrame Protected Site</web-resource-name>
<url-pattern>/demo/*</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>*</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>EnginFrame Demo Site</realm-name>
</login-config>
The /demo/* URL can be changed to the URL that matches your needs. As an example, the /* URL
protects all the contents in your web site. The <realm-name> contents are used as the challenge title
shown by browsers.
Using the Internal Credentials Database
You have to add users (and their passwords) allowed to browse your site to the authentication
database. EF_ROOT/conf/ef-users.xml is the database. This file contains a list of users with
their password hashed using SHA algorithm. EnginFrame ships the utility script
EF_ROOT/plugins/admin/bin/digest.sh that helps adding users to the database file. You
have can also use the administration portal for this task.
You can disable a user defined in the database by either deleting the line containing the user or by
commenting the line using the XML comment tags. You can also use the administration portal for
this task.
Using Apache Credentials
You could already have a user database defined for your Apache Web Server. You can integrate
Tomcat and EnginFrame to use this database instead of using EF_ROOT/conf/ef-users.xml.
40
EnginFrame Administrator's Reference
Using LDAP Credentials
Edit NICE_ROOT/tomcat/conf/server.xml adding tomcatAuthentication=false
attribute to the <Connector> used to link Apache to Tomcat via JK module.
There is no need to modify EF_ROOT/WEBBAPP/WEB-INF/web.xml when using this
configuration.
You have to protect your root context using the Location directive. An example is:
<Location */your_root_context/*>
AuthType Basic
AuthName "EnginFrame Grid Portal"
AuthUserFile /full/path/to/passwd
Require valid-user
</Location>
The value your_root_context is the one you defined when you installed EnginFrame.
The AuthName field contains a descriptive name of the protected site that is prompted to the users
when logging into the site.
The AuthUserFile contains the absolute path to the Apache user database. This file has to be created/
modified using APACHE_HOME/bin/htpasswd.
Refere to Apache's documentation for a complete explanation.
Using LDAP Credentials
It is possible to let Tomcat check credentials on an LDAP Server. Edit
EF_ROOT/conf/enginframe.xml and comment all existing <Realm> tags. Finally add before
the closing </Context> tag the following <Realm> tag with its attributes:
<Realm className="org.apache.catalina.realm.JNDIRealm"
connectionURL="ldap://ldap_server:ldap_port"
userPattern="uid={0},ou=People,dc=company.com"
roleBase="dc=company.com"
roleName="cn" />
This Realm connects to your ldap_server that is listening on ldap_port to retrieve your users
according to userPattern. This connection assumes that an anonymous connection is sufficient to
search the directory and retrieve role information. If this is not true, you need to add connectionName
and connectionPassword attributes in order to search the database.
A complete description of this Ream can be found here:
http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html#JNDIRealm
EnginFrame Administrator's Reference
41
8
Post Processor Configuration
Every request handled by EnginFrame Server is post processed before sending response back
to browser. The EnginFrame post processing is done to intercept XML tags that generate the
EnginFrame Server Pages™ (EFSP). These XML tags allow the creation of dynamic content simply
including them in the output created by the service.
processor.conf
The EnginFrame Post Processor configuration file is:
• EF_ROOT/conf/processor.conf
The tags contained in this file are used to apply EFSP to action output.
The syntax of the processor command handlers follows:
• processor.command.name=fully_qualified_class_name
• processor.name.tag=tag_to_handle
The fully_qualified_class_name is invoked to post process action output when it contains
tag_to_handle.
You can pass parameters to EFSP class as follows:
• processor.name.param_name=param_value
This ensures that EFSP corresponding to name has param_name passed as parameter. The
param_name has param_value as its contents.
The following are the default EFSP shipped by EnginFrame:
• ef:session, sets session-state parameters that are then exported in the EnginFrame environment.
• ef:reset-spooler, resets a spooler TTL and/or name.
• ef:rfb, inside RFB window displays user’s spoolers via their alias.
• ef:logout, logs out users from EnginFrame and deletes cookies created by EnginFrame itself.
EnginFrame Administrator's Reference
43
processor.conf
• ef:list-spoolers, lists user’s spoolers.
• ef:destroy-spooler, removes a spooler.
• ef:show-spooler, displays spooler's contents.
• ef:rename-spooler, changes a spooler name.
Each of these XML tags has a corresponding EnginFrame handler class. The associations between
the tags and the classes are specified by the keyword ef.processor.conf in EF_ROOT/conf/
server.conf. The default location is EF_ROOT/conf/processor.conf. The value of this
parameter must be an absolute path to the processor configuration file. This allows easy specification
of another configuration file for the EnginFrame Post Processor. The value of this parameter cannot
be empty.
44
EnginFrame Administrator's Reference