Webslinger

Introduction Copied

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 Copied

Webslinger runs as a server. It establishes TCP/IP connections to the specified 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, for example http://server1:8080. The Webslinger display contains the Hierarchy Page and Details Page.

Sample screenshots Copied

The initial view shows the state of top levels of the hierarchy plus the status of the connected Gateways.

To expand the view, click on one of the branches. To remove all the components deemed as in an ‘OK’ state, click on the button at the top of the screen.

This will only display 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 Copied

Packaging Copied

The Webslinger package contains the following files.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org).

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 Copied

Download Webslinger from the Downloads site 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.

When Security-Enhanced Linux (SELinux) is running in Enforcing mode, it may deny certain functions of Geneos depending on the implemented configurations and policies. To see which functions SELinux denies, check the audit log. The log is typically located in /var/log/audit.log, where the log type entry is AVC. The audit log provides the details of any denied access. For example, denied connection to the TCP port. If you experience issues related to this mode, you may opt to disable SELinux, or create policy modules to grant the required access. Please contact your administrator or security team for assistance. Beginning Geneos version 5.0.0, this component is only compatible with other Geneos components that are version 3.6.0 or higher. For more information, see the Geneos Compatibility Matrix.

Command line options Copied

You can use the following command line options:

Webslinger setup Copied

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.

*** GATEWAY = hostname:port
*** SECURE_GATEWAY = hostname:port

*** Example with password authentication - authentication is given after the gateway definition
*** GATEWAY = hostname:port AUTHENTICATION = username:password

*** Example with SSL certificate authentication - authentication method is given after the authentication credentials
*** SECURE_GATEWAY = hostname:port AUTHENTICATION = username AUTHENTICATION_METHOD = SSL

*** Example with hot-standby pair and password authentication
*** The password may be plain text or AES 256 encrypted (see the Webslinger Setup section of the manual)
*** GATEWAY = primary-hostname:port, secondary-hostname:port AUTHENTICATION = username:password

*** Example with hot-standby pair and SSL certificate authentication
*** SECURE_GATEWAY = primary-hostname:port, secondary-hostname:port AUTHENTICATION = username AUTHENTICATION_METHOD = SSL


**********************************************************

*** The port to listen for browser connections on.

LISTEN_PORT = 8080

**********************************************************

*** The view path to use.  This will determine the directory structure
*** to group the ManagedEntities by.

VIEW_PATH = COUNTRY, TOWN, SYSTEM

**********************************************************

*** How often to automatically refresh the pages.
*** Main refers to the page with the tree showing the ManagedEntities.
*** View refers to the pages that display the actual data in table form.
*** These do not apply to PDAs.

MAIN_REFRESH_RATE = 30
VIEW_REFRESH_RATE = 10

**********************************************************

*** SSO Authentication options

*** The base URL of the SSO Provider
*** For SSO Agent or Gateway Hub, provide hostname and port
*** SSO_PROVIDER = https://192.168.0.0:8080
*** For Obcerv, provide the base URL for the realm
*** SSO_PROVIDER = https://obcerv.example.com/auth/realms/obcerv

*** The Location of the SSO Public Key File
*** SSO_KEYFILE = /etc/geneos/ssoKeyFile.txt

*** A comma-separated list of roles (or LDAP groups) that have access to Webslinger
*** GROUPS = ADMIN, GRP1, GRP2

*** The URL of the web service
*** WEB_SERVICE_URL = http://WebServiceName

*** [Optional] The Web server's session key. Set to a unique value if
*** running more than one Webslinger instance on the same host.
*** SESSION_KEY = myWebslinger_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 Webslinger might not display the correct information in the 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 should 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.

Note

Webslinger can only connect to a Gateway once, so you should only specify either a secure connection or insecure connection, not both at the same time.

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, which means it auto-refreshes every 10 seconds.

MAIN_REFRESH_RATE — when set to a non-zero value, the hierarchy v View will automatically refresh at the defined rate. Defaults to 30, which means it auto-refreshes every 30 seconds.

SSO_PROVIDER — If this option is not set then SSO authentication is disabled.

• If the SSO provider is the SSO Agent or Gateway Hub, specify its protocol, hostname, and port. For example: https://192.168.0.0:8080
• If the SSO provider is Obcerv, specify the whole URL up to the Obcerv realm. For example: https://obcerv.example.com/auth/realms/obcerv 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----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA9KTR6IFL44UTGCs5Hi2xfISO7eMBaqf7
5BQym/E8woQE2NOocyAvshGLAaE9oHP4vqRnc+hHyDs7DDF2u0VFcYp6r4uISe+HUka+wKjfSZZF
OB5lFYzZfb7hRGvc5kMZEvg7QYBej/c37uSB9r1/T4yao3SAdHGEwlthTKf0V+TtDGvlWPKGzVdC
YowmNC0Z1RxsT/X3jhNvnkHRQYXWhwGiEKU1+U7Bgtlpzd/3UFQnZsOIMFME9R53b+Wjron04B6O
BB0jqmWFTYaoXWh2oZBK5XZ1e165HaNXAYkeC4RcHdu8M0urk8JkkRby9M8UXxCATbVrtYGosoI9
JH+t1wIDAQAB
-----END PUBLIC KEY-----

The public key used to sign Obcerv JWTs can be obtained from the auth/realms/obcerv endpoint provided by Obcerv. This produces a JSON file that looks like:

{"realm":"obcerv","public_key":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAs+MoswQTYc+J0MhLhzprJTb8U0MAd4f1X+txv9j653tsIGTsyV0ufJpsvTMk+kt/7XI1RNGuJ9IqrYenRnN1h65C6xb1ehJ0f8BCYLL+lv084RR5T7bcxAIKOEr6TUQmKSIE2uqi0EZg0MyGhAkEcDjrf7YqPPTiMCffOx+T9/yPo/wLcSluP2VdESkU0R91D9d2KGv0LmzWFLHRN9Ag70EWokM4Cw+/zi32ZqQEGlTA1G7YyEM+FlbrYPSYiBe1toCJ3fKJE1xvrp7+kj4imxWd5l0ljs/233DCcBVEM46UJ5cupTptZfTGnP/9NbrYySMpT6wga5eK2y28AdOFJQIDAQAB","token-service":"https://cconfig-playground.itrslab.com/auth/realms/obcerv/protocol/openid-connect","account-service":"https://cconfig-playground.itrslab.com/auth/realms/obcerv/account","tokens-not-before":0}

The key needs to be line-wrapped with the added PEM Public key header and footer using the following bash script:

#!/bin/bash
obcerv_url=$1
echo "-----BEGIN PUBLIC KEY-----"
curl -s -k ${obcerv_url}/auth/realms/obcerv | jq -r .public_key | fold -w 40 -
echo "-----END PUBLIC KEY-----"

GROUPS — set of comma-separated values that define the Obcerv roles, or LDAP user groups for SSO Agent or Gateway Hub, that are allowed to access Webslinger.

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.

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 Copied

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, start Webslinger with a -key-file <filename> parameter. This tells the Gateway to use the key within this file for all encryption and 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 -nosalt -aes-256-cbc -k "Now is the winter of our discontent" -P -md sha1
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 you are using 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 Copied

The Secure Gateway allows for authentication using either a password (see Securing Gateway Authentication) or an SSL Certificate.

Caution: When you connect to Webslinger using an SSO-enabled Gateway, an error may occur:
ERROR: Authentication with Gateway 192.168.101.42:36039 failed: No login credentials for connection

Webslinger only supports password and SSL authentication.

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 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 Copied

To generate a public certificate and private key for Webslinger, see the 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 Copied

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 SSL Certificate. See Get the fingerprint and subject of an SSL Certificate.

Cookies Copied

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 Copied

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 Copied

By default, Webslinger will log to its binary’s directorywith timestamps for each entry written in the ISO-8601 format. 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 Webslinger logging behaviour using either:

• Command Line Options.
• Environment variables.

Via command line Copied

Launching the Webslinger executable with the -logoption allows the creation of the log in a different directory:

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

You cannot change the log time format using command line options.

Via environment variables Copied

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

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

You can also change the log time format that is used to record the timestamp that begins each line of the log file. For example:

export LOG_TIME_FORMAT=ISO-8601-UT

For more information on these environment variables, see variables.

Required libraries Copied

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) Copied

Suse (64-bit) Copied