Driven Administrator Guide: Installing and Configuring the Driven Server

version 2.2.6

Driven Administrator Guide: Installing and Configuring the Driven Server

1. Prerequisite

1.1. Upgrading

1.2. Check your team’s demands and expectations

1.3. Check your hardware and software

2. Planning a Driven Deployment

2.1. Understanding the Deployment Architecture

2.2. External Dependencies

2.3. Selecting a Deployment Topology

3. Installing and Configuring the Driven Server

3.1. Downloading the Driven Server

3.2. Installing the Driven Server

3.3. Configuring the Driven Server

4. Starting and Stopping the Driven Server

4.1. Starting the Driven Server

4.2. Stopping the Driven Server

5. Uninstalling the Driven Server

5.1. Stopping the Server

5.2. Removing All Files and Data

6. Using the Driven Admin Features

6.1. Manage Users

6.2. Managing A Single User

6.3. Manage Teams

6.4. Manage System

7. The Driven Command Line Client

7.1. Installing the Driven CLI Client

7.2. Backing Up and Restoring Driven Repositories

7.3. Backing Up Your Driven Data

7.4. Extracting Data with the scope Command

7.5. Examples of Command Usage

7.6. Common Command-Line Options

7.7. How-To Tips

8. Integrating with Third-Party Monitoring Applications

8.1. Using Java Management Extensions (JMX) with Driven

8.2. Using Nagios Plugins with Driven

9. Upgrading Driven Server

9.1. Before WAR Replacement

9.2. Upgrade the Driven Server

10. Troubleshooting Driven

10.1. The Driven Server installation generates a Java incompatibility error

10.2. Can not install a valid license

10.3. Transmission of application metrics data to Driven stops but app status remains in RUNNING state

Installing and Configuring the Driven Server

Downloading the Driven Server

Step 1: Download the Driven Server installation ZIP archive, which includes Apache Tomcat and embedded Elasticsearch libraries, by one of the following methods:

  • Download the ZIP archive directly with this hyperlink: driven-tomcat-2.2.6.zip

  • Alternatively, on UNIX, Linux, and Mac, run the following command:

$ wget -i http://files.concurrentinc.com/driven/2.2/driven-server/latest-tomcat.txt

The ZIP archive is packaged to address all interdependencies.

Step 2: Unzip the Driven installation package

Extract the installation package into your installation directory.

$ unzip driven-tomcat-2.2.6.zip
$ cd driven-tomcat-2.2.6
Tip
 If you already have a servlet container that you want to use as the web server, deploy the WAR file from the extracted Driven installation package as the ROOT context.

Installing the Driven Server

Installing Elasticsearch for Clustered Production Environments

You must perform stand-alone Elasticsearch installation if you are deploying Driven on multiple nodes.

Before you begin Elasticsearch installation:

  • See the Driven Compatibility Matrix section of the Planning a Driven Deployment page to ensure that you install a compatible version of Elasticsearch.

It is recommended to use the operating system packages provided by elasticsearch. These will set up a user to run the elasticsearch daemon. We recommend setting up at least 3 Elasticsearch nodes for a highly available setup. We recommend also deploying on mid-size machines, since elasticsearch works better when the heap is not too big. This has to do with garbage collector settings and is beyond this guide. We recommend running elasticsearch with a heap size of 8G.

Below you will find recommended settings for a driven deployment that are different from the defaults in elasticsearch.yml. An explanation of each setting is below each item:

cluster.name: driven

Sets the name of the cluster to driven. The name can be anything, as long as the driven server and elasticsearch use the same name.

bootstrap.mlockall: true

Makes sure that the elasticsearch daemon never swaps.

indices.fielddata.cache.size: 75%

Limits the field data cache to use a maximum of 75% of the heap.

indices.memory.index_buffer_size: 50%

Allows the index buffer to take up to 50% of the heap.

threadpool.bulk.type: fixed
threadpool.bulk.size: 60
threadpool.bulk.queue_size: 300

Sets the bulk thread-pool to a fixed pool of 60 threads with a queue size of 300 items. Driven makes heavy use of the bulk api and requires a large enough queue size on busy servers.

script.disable_dynamic: false

Some functionality in Driven requires the dynamic scripting feature of Elasticsearch.

Further reading

See Elasticsearch Reference for more information.

Configuring the Driven Server

Configure the Driven Server by using the driven.properties file that is in the ${INSTALL_DIR}/conf/ directory. (Throughout the documentation, ${INSTALL_DIR} stands for the Driven installation directory name. In general, values embedded in dollar-sign and curly-bracket syntax are usually variables that should be replaced with your real values.) Most required configuration tasks pertain to interoperability with Elasticsearch, which provides the datastore that Driven uses for persistence. You must also configure SMTP properties if you want to enable notifications features in Driven.

Configuring Connectivity to Elasticsearch

The driven.storage parameters in the driven.properties file configure connections to the Elasticsearch datastore. The parameters that you need to set and how you set them depends on the deployment environment that you are selecting. Follow the section below that pertains to your deployment.

Driven Storage Parameters for Embedded Elasticsearch Nodes

If you are deploying a basic single-node Driven Server installation with an embedded Elasticsearch datastore, review the settings of driven.storage properties. While most default settings in the driven.properties file are sufficient for the Driven Server to start up, the following parameters might need to be adjusted for your needs:

  • HTTP API Access: Set the following parameter to true if you want to permit API access to Elasticsearch on port 9200.

driven.storage.http.enable

  • CORS Requests: Set the following parameter to true if you want to enable cross-origin resource sharing (CORS) requests. The CORS mechanism can be useful for troubleshooting, such as running the elasticsearch-head plugin.

driven.storage.http.cors.enabled

  • Data Storage Location: By default, data is stored in the /driven directory, which is in the main directory of the Driven-packaged Tomcat installation. If you want to save data in a different location, specify the path in the following parameter.

driven.storage.data.path
Note
 Most driven.storage properties are ignored when running with an external Elasticsearch datastore. When the datastore is external, Elasticsearch uses the settings in its own configuration file (elasticsearch.yml).
Driven Storage Parameters for External Elasticsearch

To use an external Elasticsearch cluster, you must change the driven.properties file to tell Driven how to communicate with the Elasticsearch cluster. You can also customize settings for embedded Elasticsearch persistence, such as where the data is written to disk.

Review the following driven.properties file parameter information if you are deploying Driven to a clustered production environment:

  • runlocal Property: Set this property to false as shown in the following:

driven.storage.runlocal=false

  • Elasticsearch Host Information: You must specify the nodes of the Elasticsearch cluster by setting the driven.storage.cluster.discovery.unicast.hosts parameter. Set the parameter using the format in the following line, substituting ${NODE_1}, ${NODE_2}, and ${NODE_3} with distinct host IP or DNS values for your environment:

driven.storage.cluster.discovery.unicast.hosts=${NODE_1}:9300,${NODE_2}:9300,${NODE_3}:9300

  • Elasticsearch Cluster Name: You must specify the Elasticsearch cluster name for Driven. The setting for this property must match the setting for the cluster.name property in the elasticsearch.yml file for the external Elasticsearch cluster.

driven.storage.cluster.name

Enabling SMTP Notifications

You must enable and configure SMTP for Driven if you want the deployment to operate with notifications. Notifications support the Teams feature of Driven. (See Configuring Teams for Collaboration in the Driven User Guide for more information about this feature.) Notifications also are required if you want to allow users to reset their Driven passwords.

  1. Enable and configure SMTP by setting the relevant parameters in the following properties list. In the following list, most parameter settings are only examples to show the format and source for your environment’s settings.

    driven.smtp.enabled=true
driven.smtp.host=yoursmtphost.yourdomain.com
driven.smtp.port=587
driven.smtp.tls=true
driven.smtp.username=yourusername
driven.smtp.password=yourpassword
driven.smtp.from=info@yourdomain.com

  2. Configure Driven with its external URL so that emails contain the correct hyperlinks by setting the following property:

    driven.http.url=http://${HOST_NAME}:${PORT_NUMBER}

Access to Monitored Application Information

Driven teams are modeled to facilitate full access to application performance only to users who should have such permissions. By belonging to a team, a Driven user is associated with an API key that provides insight to all execution details of a particular application. However, administering and troubleshooting a full-scale data application environment often requires the flexibility to share some of the performance data with other Driven users who do not belong to the same team.

You can configure any of the two driven.apps.discoverability parameters and the two driven.apps.visibility parameters to control how broadly monitored applications and application execution details can be accessed or shared among users of different Driven teams. You can also set whether team leaders and the Driven system administrator are allowed to make access-control decisions instead. After the Driven Server is deployed and in production, neither an administrator nor a regular user can override the settings of these parameters unless they stop the server and reconfigure the driven.properties file.

The parameters determine how the following access-control levels are implemented:

  • Discoverability: A monitored application is discoverable for a user when the user can see the application on the Show All Apps page, in a Status View, or in an Application View. Clickable elements and links in the tables that go to deeper execution details do not function if the user does not have visibility rights.

  • Visibility: A user has visibility access to an application when the user can see details about an application execution, including unit-of-work and slice performance data.

Note
 Discoverability and visibility operate independently of each other. Access to more detailed information (visibility) does not necessarily entail ability to see the same application in the higher-level Status View, Application View, or Show All Apps page.
Discoverability

By default, applications are discoverable by anyone logged in to Driven. Change the following parameter to false if you want to disable system-wide discoverability.

driven.apps.discoverability.default=true

By default, a team leader or a Driven administrator can change whether or not an application is discoverable. Change the following parameter to false if you do not want to grant team leaders or an admin permission to configure discoverability.

driven.apps.discoverability.team.config=true
Visibility

By default, application details are not visible to Driven users who do not belong to the team that is associated with the application. Change the following parameter to true if you want non-members to be able to view application details by default on newly created teams.

driven.apps.visibility.default=false

By default, a team leader or a Driven administrator can change whether or not an application’s details are visible. Change the following parameter to false if you do not want to grant team leaders or an admin permission to configure visibility.

driven.apps.visibility.team.config=true

LDAP Integration

Driven can be configured to delegate authentication to an LDAP directory. Driven will lazily create Driven users from LDAP users after the first successful login.

This is read-only integration. Nothing is written back to the LDAP directory. It supports authentication only, no roles are resolved from LDAP.

Being read only, some operations are not allowed on LDAP users, such as resetting password through Driven. Operations allowed on LDAP accounts are:

  • Switching the user to a Driven Admin role.

  • Deleting/deactivating them in Driven, no modifications are propagated into the LDAP directory

Team membership, admin status, and user created content and preferences, such as Saved Views, are managed through Driven and that information remains in Driven.

Migrating existing users

Migration of existing Driven users onto LDAP can be done in the following way:

  1. The user logs into his/her existing Driven account.

  2. Look up and invite his/her corresponding LDAP person to all his/her teams.

  3. Then the internal Driven account should be renamed or deleted.

  4. The user can then login using LDAP credentials and accept all pending invitations.

To enable LDAP integration, the following properties need to be specified in the driven.properties file. Example values below will need to be replaced with values matching your LDAP directory

Base Configuration

  • Authentication realms: Values can be 'internal' and 'ldap'. This is a comma-separated list, and the order matters for determining the precedence in which authentication is tried. No value defaults to internal. The initial Admin user is in internal realm.

driven.account.auth.realms=internal,ldap

  • LDAP server URL: The url must be reachable from driven server in order for Driven to make authentication requests.

driven.ldap.env.java.naming.provider.url=ldap://example.com:389
Binding

  • Authentication mechanism: Specify the binding authentication mechanism.

driven.ldap.env.java.naming.security.authentication=simple

  • Principle: The user which will be used to bind to the directory.

driven.ldap.env.java.naming.security.principal=cn=Manager,dc=example,dc=com

  • Credential: The password for the Principle used to bind to the directory.

driven.ldap.env.java.naming.security.credentials=managerPassword
Search and Lookup

  • User DN template: The DN template for users.

driven.ldap.user.dn.template=uid={0},dc=example,dc=com

  • Search base DN: Base DN for user lookup

driven.ldap.search.base.dn=dc=example,dc=com

  • Username attribute: LDAP attribute serving as a unique username

Note
 The user DN template value above is the username attribute combined with base DN value. They should match. 
driven.ldap.attr.username=uid

  • Email attribute (optional): If the email attribute is specified, it will allow setting the Driven user’s email when creating Driven users on first LDAP authentication.

driven.ldap.attr.email=mail

  • OU attribute (optional): An attribute on user defining their out. Please note that it is supported as an attribute on User’s record in LDAP, not as a part of DN. We support a single DN template value, so users should reside in one location in the directory.

driven.ldap.attr.ou=ou
Pass-through Properties

Driven can pass through properties to the directory connection. If there is a need to fine tune the LDAP connection you can add the standard java.naming properties prefixed by 'driven.ldap.env.'

See https://docs.oracle.com/javase/7/docs/technotes/guides/jndi/jndi-ldap-gl.html for available options.

For example

driven.ldap.env.java.naming.referral=follow

Invitation and lookup behavior

  • Disable lookup for invitations: By default users can lookup and search for users to invite to their teams. The admin may wish to disable this ability and not allow users to see a list of existing users for invite. This can be disabled with a server property. Then a user will have to type in username or email address of the person to invite to team explicitly.

driven.account.lookup.list.enabled=false

  • Create user from email invite: By default, users can only invite existing Driven users to join their teams. However, the admin can choose to configure invites to create a user and team by email address, if the user does not already exist in Driven. When a user invites a user by an email address which does not already exist, a user will be created with the email as username. In addition a team will be created for that user using the email as the team name.

driven.account.create.on.email.invite=true
© 2014-2016 Concurrent, Inc. All rights reserved.