Galvanometer

The AMPS Galvanometer provides an extensive set of visualizations of the state of the instance. Galvanometer also provides the ability to query the instance and display the results.

Understanding Galvanometer

Galvanometer is a JavaScript application that uses the administrative monitoring interface to provide information about an AMPS instance. Galvanometer also includes a lightweight, read-only AMPS client application (using the AMPS Javascript client) that can be optionally enabled to inspect data in the instance.

Using TLS/SSL with Galvanometer

When the Admin interface is configured to use TLS/SSL, Galvanometer will also use TLS/SSL with the certificate and key file specified.

For the replication graph to be correctly displayed, the instances that replicate to each other must either all use TLS/SSL for the Admin interface or none of the instances can use TLS/SSL for the Admin interface.

If some of the instances in the replication graph use TLS/SSL for the Admin interface and some do not, the information shown in the replication graph will be incomplete.

Authorization and Entitlement in Galvanometer

In order to enable Galvanometer to provide credentials to the AMPS instance (in case it is required to access AMPS monitoring information), the special WWWAuthenticate option is supported. This option specifies how credentials will be provided to AMPS.

The option can have the following values:

• Negotiate (Kerberos)

• NTLM

• Basic realm="<SECURITY_DOMAIN>" (Basic Auth)

When using Negotiate or NTLM, Galvanometer will automatically supply corresponding authorization tokens to AMPS. If Basic Auth is used for authorization, the Login/Password dialog will require a user to enter credentials.

<Admin>
    ...

    <WWWAuthenticate>Basic realm="AMPS Admin"</WWWAuthenticate>

    ...
</Admin>

Statistics Entitlement

Galvanometer uses queries of the HTTP admin interface to provide the state of the instance. These queries are handled as any other query of the admin interface. If the user does not have permission to view a particular path in the Admin interface, the AMPS Admin interface will not provide that data and Galvanometer will not show meaningful results for those statistics.

As described in the Entitlement section of this guide, the AMPS entitlement system treats statistics retrieval as a read request to an admin resource type. A user that is not entitled to retrieve a specific admin resource cannot view those statistics, and so Galvanometer will not show that information.

Entitlement to Administrator Actions

As with requests for statistics, the AMPS entitlement system treats a request for an administrative action as a read request to an admin resource type. A user that is not entitled to access that resource will not be able to run the action.

For actions that can alter server state (such as disconnecting a client), Galvanometer will run an entitlement check to see if the current user has permission to perform the action. The results of this entitlement check are used to determine how Galvanometer will display the control for that action. The control may be hidden or shown as disabled if the current user does not have permission to that action. These entitlement checks do not indicate that the action has been performed.

See the Entitlement section of this guide for more information.

Using Anonymous Paths

The AnonymousPaths option allows Galvanometer to bypass authentication and/or entitlement for Admin paths that match a regular expression. For resources that match the AnonymousPaths option, the Admin interface does not require authentication and does not check entitlements.

The most common use of AnonymousPaths is to allow Galvanometer to correctly display the replication graph when the instance is configured to use Negotiate or NTLM for authorization. Galvanometer determines the replication graph by polling the instances that participate in replication. Since most browsers disallow sending cross-domain authorization tokens, it is necessary to provide access to replication paths without requiring authorization for Galvanometer to be able to display the replication graph. For installations that use Negotiate or NTLM, Galvanometer may not be allowed to construct a replication graph if this option is not set.

AnonymousPaths can also be used to provide access to a specific resource, without allowing access to any other information in the Admin interface. For example, an instance might specify ^/amps$ for unauthenticated users to be able to verify that the instance is running and processing Admin requests, but without allowing those users to obtain any other data about the instance.

The following example shows how to add an AnonymousPaths directive that allows any connection to access replication information about the instance.

<Admin>
   <!-- ... other configuration here ... -->

   <!-- Specify anonymous paths. In this
        case, allow any user to access replication
        information. -->

   <AnonymousPaths>^/amps/instance/replication</AnonymousPaths>
</Admin>

The AnonymousPaths option is disabled by default.

Make Replication Page Work with NTLM / Negotiate Authentication

When using Negotiate or NTLM for authorization and/or entitlement, it prevents Galvanometer from correctly displaying replication graphs by forbidding access to destination instances of AMPS since most browsers disallow sending cross-domain authorization tokens that are required in order to authorize AJAX data requests from a browser.

Enabling Queries and Subscriptions in Galvanometer

Much of the functionality available in Galvanometer uses the basic monitoring interface.

Galvanometer submits queries and subscriptions to AMPS using the websocket protocol. To use these functions in Galvanometer, you must provide the name of a Transport of type websocket for Galvanometer to use.

For example, the following directive specifies that Galvanometer will use the Transport with the Name of websocket-any to submit commands to AMPS.

<Admin>
   <!-- ... existing configuration ... -->

   <!-- Look up the transport named websocket-any in
        this config file, and make connections to
        that Transport for sending commands to AMPS. -->
   <SQLTransport>websocket-any</SQLTransport>
</Admin>

The configuration block above requires that the AMPSConfig file contains a Transport with the Name of websocket-any of Type websocket.

When this configuration item is specified, Galvanometer will enable the query and subscription capabilities, and submit commands to AMPS over the specified Transport. The queries and subscriptions use the AMPS JavaScript client to connect to AMPS.

For example, the websocket-any transport referenced in the snippet above might be defined as follows:

<Transports>
   <!-- ... existing transports remain ... -->

    <Transport>
        <Name>websocket-any</Name>
        <Protocol>websocket</Protocol>
        <Type>tcp</Type>
        <InetAddr>9008</InetAddr>
    </Transport>

</Transports>

Notice that Galvanometer connects as a client using this Transport. There is no special transport or protocol for Galvanometer, and the security configured for the instance (or the Transport) applies to Galvanometer.

If the Transport is configured to use TLS/SSL, it must use certificates signed by a certificate authority (CA) known to the browser that will be used to access AMPS. For security reasons, browsers disallow self-signed certificates by default. This means that, although a client application may be able to connect, a browser will not allow a websocket connection to a transport that uses a self-signed certificate.

Queries and Subscriptions with Basic Auth in Galvanometer

When Basic Auth is used for authorization and entitlement, an additional option TrustedAdmin allows Galvanometer to use a valid session cookie created after successful authorization to the Admin API for queries and subscriptions. This option forces AMPS to reuse credentials supplied by Galvanometer for websocket connections created by Galvanometer.

<Protocols>

    ...

    <Protocol>
        <Name>websocket-portal</Name>
        <Module>websocket</Module>

        <!-- disabled by default -->
        <TrustedAdmin>enabled</TrustedAdmin>

    </Protocol>

    ...

</Protocols>

TrustedAdmin is only supported by the websocket-based protocols and is disabled by default.

Disabling Galvanometer

Galvanometer is enabled in the monitoring interface by default. To disable Galvanometer, add the following directive to the Admin configuration block:

<Admin>
   <!-- ... existing configuration ... -->
   <Galvanometer>disabled</Galvanometer>
</Admin>

Disabling Galvanometer with this configuration item has no effect on the basic monitoring interface.