Webslinger - Technical Reference

Introduction

Geneos Webslinger is an application which provides the Gateway output in a view-only HTML format. It enables users and managers to view the status of their environment in near real-time via a web browser.

Architecture

Webslinger runs as a server. It establishes TCP/IP connections to the specified Geneos Gateways and acts as a Web Server, serving pseudo-pages that reflect the latest status of the Managed Entities from the connected Gateways.

To view details of your environment, enter the name of the Webslinger server host and the Webslinger configured Listen Port number into the Browser Address field, e.g. http://server1:8080. The Webslinger display contains the Hierarchy Page and Details Page.

Sample Screenshots

The Initial view shows the state of top levels of the hierarchy plus the status of the connected gateways. To expand a view, simply click on one of the branches. To remove all the components deemed as in an ‘OK’ state, click on the image11 button at the top of the screen.

This will display only elements which have been identified as requiring attention.

To view the details of any component requiring attention, expand the branch to its lowest level, and click on the specific Managed Entity. This will drill down to the variable that has been identified as operating outside acceptable parameters.

Set up and configuration

Packaging

The Webslinger package contains the following files:

FileDescription
webslinger.linuxThe main Linux Webslinger binary.
webslinger.setup.tmplTemplate setup file.
webslinger.sunThe main Solaris Sparc Webslinger binary.
webslinger.resResource file.
lib/libcrypto.so.1.0.0OpenSSL library, required by libcurl.so to provide cryptographic functions for authentication.
lib/libssl.so.1.0.0OpenSSL library, required by libcurl.so to provide support for HTTPS URLs.

Note: There is no option to specify the location of the webslinger.res file. If you change the default launch location of your Webslinger binary you must create a symlink to the resources file within that directory. For example, launching the file from /root requires the resource directory to be specified using this command:

ln -s /usr/local/geneos/webslinger/webslinger.res /root/webslinger.res

Installation

Download Webslinger from the client area of the ITRS website and extract into your installation directory. Amend the webslinger.setup file so that it points to the Gateways that you wish to view through your web browser and then execute the Webslinger binary.

Command Line Options

-ssl-certificateThis is the file that contains the signed SSL server certificate (in PEM format)
-ssl-certificate-keyThis is the file that contains the signed SSL server private key (in PEM format). If this is option not specified but the certificate is then the Webslinger will look for the private key in the same file as the server certificate
-ssl-certificate-chainThis is the file that contains the trusted certificate authority.
-secureIf this option is present, Webslinger will listen on a secure port rather than an insecure port. If -secure is specified, then an SSL server certificate and an server private key also need to be specified.
-key-fileTells Webslinger to use the key within this file for decoding AES-256 passwords.
-aes256-encrypt <password> [-key-file <file>]Webslinger will output the AES-256 encrypted password, optionally using a specified key file.
-log <logfilename>Overrides the log file name and location. See Webslinger log for more information.
-nologDisables logging.
-setupSpecifies the location of set-up files.
-minTLSversionSpecifies the minimum TLS version. The accepted values are:
  • 1
  • 1.0
  • 1.1
  • 1.2
For more details, see Secure Communications.

Webslinger Setup

The setup file is a text file. Please see example below.

********************************************************************************************* 
*** WEBSLINGER setup file
*********************************************************************************************
*** List of Gateways to connect to.
*** One line per Gateway.
*** Port should be the Gateway's EMF2_PORT

*** Stand-alone Gateway or Secure Gateway with no authentication
GATEWAY = hostname:port
SECURE_GATEWAY = hostname:port
								
*** Stand-alone Gateway or Secure Gateway with password authentication
*** Passwords can be plain text or AES-256 encrypted 
GATEWAY = hostname:port AUTHENTICATION = user:password
SECURE_GATEWAY = hostname:port AUTHENTICATION = user:+encs+D3689B794A64A248B2B243A57BD3885A

*** Stand-alone Secure Gateway with SSL Certificate authentication
*** SSL Certificate authentication only available with Secure Gateways
SECURE_GATEWAY = hostname:port AUTHENTICATION = username AUTHENTICATION_METHOD = SSL
*** Hot-standby enabled Gateway pair with no authentication GATEWAY = primary-hostname:port, secondary-hostname:port *** Hot-standby enabled Gateway pair with authentication GATEWAY = primary-hostname:port, secondary-hostname:port AUTHENTICATION = admin:+encs+D3689B794A64A248B2B243A57BD3885A *** Hot-standby Secure Gateway pair with SSL certificate authentication SECURE_GATEWAY = primary-hostname:port, secondary-hostname:port AUTHENTICATION = username AUTHENTICATION_METHOD = SSL
LISTEN_PORT = 8080 VIEW_PATH = COUNTRY , TOWN, SYSTEM VIEW_REFRESH_RATE = 10 MAIN_REFRESH_RATE = 30 ********************************************************** *** SSO Authentication options *** All the following are enabled only when using SSO Authentication: *** SSO_PROVIDER = https://192.168.0.0:8080 *** SSO_KEYFILE = C:\itrs\ssoKeyFile.txt *** GROUPS = ADMIN, GRP1, GRP2 *** WEB_SERVICE_URL = http://WebServiceName *** SESSION_KEY = WebServiceName_8080

GATEWAY - specifies the name of the Geneos Gateway host and port number. Webslinger can connect to multiple Gateways, and each Gateway should be specified on a separate line.

If two Gateways are configured as hot-standby pair, then they must be configured on the same line with a comma separating the two. The Primary gateway must be configured first followed by the Secondary gateway.

Warning: If you have the same name for dataviews and entities in your Gateway, then Web Slinger might not display the correct information in State Tree. To avoid this, ensure that the dataview and entities names are unique.

If a Gateway is configured for user authentication then the details for each Gateway connection should be included after AUTHENTICATION on the same line (see example above). The user and password is specified as user:password and the password may be plain text or AES-256 encrypted (see Securing Gateway Authentication).

SECURE_GATEWAY - specifies the name of the Geneos Gateway host and port number. As with GATEWAY, each SECURE_GATEWAY line be used to specify a connection to a stand-alone gateway or a connection to a hot-standby pair.

If SECURE_GATEWAY is used, Webslinger connects to a Gateway using a secure connection. If GATEWAY is used, Webslinger connects to a Gateway using an insecure connection.

The optional field AUTHENTICATION_METHOD can be added to the SECURE_GATEWAY line to allow for SSL Certificate authentication. For more information, see SSL authentication on a Secure Gateway.

LISTEN_PORT - the port number that Webslinger will use to listen for web browser connections. The default value is 8080.

VIEW_PATH - Webslinger builds the Managed Entity hierarchy tree in the order of the attributes defined by the VIEW_PATH. These attributes must match the Attributes configured in the Managed Entity section of the Gateways.

VIEW_REFRESH_RATE - when set to a non-zero value, the Managed Entity View will automatically refresh at the defined rate. Defaults to 10, i.e. auto-refresh every 10 seconds.

MAIN_REFRESH_RATE - when set to a non-zero value, the Hierarchy View will automatically refresh at the defined rate. Defaults to 30, i.e. auto-refresh every 30 seconds.

SSO_PROVIDER - the URL and port of the Single-Sign-On (SSO) agent. If this option is not set then SSO authentication is disabled.

SSO_KEYFILE - The location of the file containing the public key of the SSO service. This key is used to verify that all JWT tokens have been generated by the SSO service and have not been manipulated by a third party. If the key cannot be verified then SSO authentication is disabled.

The key must be in PEM format, with lines no longer than 76 characters. For example:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA9KTR6IFL44UTGCs5Hi2x
fISO7eMBaqf75BQym/E8woQE2NOocyAvshGLAaE9oHP4vqRnc+hHyDs7DDF2u0VF
cYp6r4uISe+HUka+wKjfSZZFOB5lFYzZfb7hRGvc5kMZEvg7QYBej/c37uSB9r1/
T4yao3SAdHGEwlthTKf0V+TtDGvlWPKGzVdCYowmNC0Z1RxsT/X3jhNvnkHRQYXW
hwGiEKU1+U7Bgtlpzd/3UFQnZsOIMFME9R53b+Wjron04B6OBB0jqmWFTYaoXWh2
oZBK5XZ1e165HaNXAYkeC4RcHdu8M0urk8JkkRby9M8UXxCATbVrtYGosoI9JH+t
1wIDAQAB -----END PUBLIC KEY-----

GROUPS - A set of comma-separated values that define the user groups that are allowed to access Webslinger. This option is only used if SSO authentication is enabled.

An asterisk (*) can be used as a wildcard to indicate any authenticated user. For example:

GROUPS = * # any authenticated user
GROUPS = EMEA* # any authenticated user in EMEA

WEB_SERVICE_URL - the URL of Webslinger. This is required if using SSO authentication.

Note: If the WEB_SERVICE_URL provided does not contain a port, Webslinger appends the URL with the port in the LISTEN_PORT parameter. If the WEB_SERVICE_URL provided does contain a port, Webslinger takes the URL as written and does not append with a port.
This may of be of note when Webslinger is behind a Load Balancer; in this case, the appropriate port should be added to WEB_SERVICE_URL and will override the LISTEN_PORT when Webslinger communicates with the SSO Agent.

SESSION_KEY - sets the name of the session (cookie) for Webslinger. If absent, the default value is 'sessionId'. Multiple instances of Webslinger on the same host require a unique value for each instance. This option is only used if SSO authentication is enabled.

Securing Gateway Authentication

Both the Gateway and Secure Gateway sections of the configuration allow you to specify authentication in the form of a username:password combination:

GATEWAY = ... AUTHENTICATION = username:password

The Secure Gateway also allows for SSL Certificate authentication. For more information, see SSL authentication on a Secure Gateway.

The password provided for authentication can be either plain text or AES-256 encrypted. You can get Webslinger to encrypt a password for you with:

webslinger -aes256-encrypt <password>

It is recommended that you use the most secure method of storing your passwords possible within your configuration. Currently this is an AES-256 implementation.

By default the Webslinger uses a default key. You may wish to supply your own key to increase the security of your passwords.

Warning: When you do this any existing AES 256 encrypted passwords will no longer be valid.

To do this you start Webslinger with a -key-file <filename> parameter. This tells the Gateway to use the key within this file for all encryption / decryption of AES passwords.

An AES-256 key has two parts: a key and an initialisation vector. You can generate this using the openssl tool on the command line.

For example:

>openssl enc -aes-256-cbc -k "Now is the winter of our discontent" -P -md sha1
salt=359D12769B1F9446
key=92358925C00DE524B4F325A7F488DF1F29646313F6D258090818E8C9B69CF4D8
iv =B8B606E4700FE4D05E24E1A682F5963D

You will see a different result each time you run this command. The -key-file parameter specifies a file that has “key=…” and “iv =…” lines. You can either copy these lines into a file or redirect the output of this command into a file. However, if the output of this command changes you will need to reformat into a valid key file.

Given that you can start a Webslinger with a different key you also need a way to generate passwords on the command line using this key. The –aes256-encrypt option has been extended to use a key file.

webslinger -aes256-encrypt <password> [-key-file <key-file>]

Assuming a Linux Webslinger a real example command line could look like:

webslinger.linux -aes256-encrypt PassW0rd -key-file shh.aes

SSL authentication on a Secure Gateway

The Secure Gateway allows for authentication using either a password (described above) or an SSL Certificate.

To use an SSL Certificate instead of a password for authentication, the AUTHENTICATION_METHOD = SSL field must be added on the end of the SECURE_GATEWAY line:

SECURE_GATEWAY = hostname:port AUTHENTICATION = username AUTHENTICATION_METHOD = SSL

When the SSL authentication method is specified, the Webslinger's SSL Certificate is used to authenticate itself to the Gateway.

When AUTHENTICATION_METHOD = SSL is enabled the password field should be empty (e.g.'username'). If the password field is not empty it is ignored. If the AUTHENTICATION_METHOD field is absent, the authentication defaults to using a password.

Note: The AUTHENTICATION_METHOD field also accepts PASSWORD as an option (AUTHENTICATION_METHOD = PASSWORD).

Generate an SSL Certificate and private key pair

To generate a public certificate and private key for Webslinger, see the examples in Secure Communications. The process is identical as generating a certificate and private key for the Gateway or Netprobe. The certificate for Webslinger should be generated by the same Certificate Authority as the certificate issued for every Gateway that Webslinger will connect to.

Get the fingerprint and subject of an SSL Certificate for Webslinger

Webslinger connects to the Gateway as a user and requires an SSL Identity to authenticate itself. The identity can be the fingerprint or subject of Webslinger's SSL Certificate. See Get the fingerprint and subject of an SSL Certificate in Secure Communications.

Cookies

Webslinger makes use of cookies files on the client side. These are used to store user preferences. If SSO authentication is enabled an additional cookie containing a unique session ID is generated (SESSION_KEY). No specific installation for this is necessary, although cookies will need to be enabled on the client browser.

Authorising an SSO User

If SSO authentication is enabled, users need to be authorised before being granted access to Webslinger. Webslinger will redirect the user to the SSO Agent in order to obtain an SSO Token.

After verifying the validity of the SSO Token and checking that the user is part of a group that is allowed to access Webslinger, access is granted.

Webslinger log

By default, Webslinger will log to its binary's directory. For example, if the path to the executable is:

/usr/local/geneos/webslinger/webslinger.linux_64

Then by default a log file is created within its directory:

/usr/local/geneos/webslinger/webslinger.log

It is possible to change where Webslinger logs to using either:

Via command line

Launching the Webslinger executable with the -logswitch allows the creation of the log in a different directory. An example of this command is:

/usr/local/geneos/webslinger# ./webslinger.linux_64 -log /usr/local/geneos/webslinger/logs/websling.txt

Via environment variables

Another way to change where Webslinger logs to is to create a start script that sets an environment variable. For example, using csh:

setenv LOG_FILENAME /usr/local/geneos/webslinger/logs/webslinger.log

or using Bash:

export LOG_FILENAME=/usr/local/geneos/webslinger/logs/webslinger.log

Required libraries

The linux version of Webslinger currently requires the following libraries to run. These are listed along with the packages they can be found in for the following 64-bit operating systems.

CentOS (64-bit)

Library NamePackage Name
libnsl.so.1glibc-2.5-34.i686
libpthread.so.0glibc-2.5-34.i686
libdl.so.2glibc-2.5-34.i686
libcrypt.so.1glibc-2.5-34.i686
libutil.so.1glibc-2.5-34.i686
libstdc++.so.5compat-libstdc++-33-3.2.3-61.i386
libm.so.6glibc-2.5-34.i686
libgcc_s.so.1libgcc-4.1.2-44.el5.i386
libc.so.6glibc-2.5-34.i686
ld-linux.so.2glibc-2.5-34.i686

Suse (64-bit)

Library NamePackage Name
libnsl.so.1glibc-32bit-2.4-31.2
libpthread.so.0glibc-32bit-2.4-31.2
libdl.so.2glibc-32bit-2.4-31.2
libcrypt.so.1glibc-32bit-2.4-31.2
libutil.so.1glibc-32bit-2.4-31.2
libstdc++.so.5compat-libstdc++-5.0.7-22.2
libm.so.6glibc-32bit-2.4-31.2
libgcc_s.so.1libgcc-4.1.0-28.4
libc.so.6glibc-32bit-2.4-31.2
ld-linux.so.2glibc-32bit-2.4-31.2