Webslinger - Technical Reference

Architecture

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.

Packaging

The Webslinger package contains the following files:

Note: 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

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

Command Line Options

You can use the following command line options:

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 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 — 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 — 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, 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 -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 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

The Secure Gateway allows for authentication using either a password (see Securing Gateway Authentication) 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 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).

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 Webslinger logging behaviour using either:

• Command Line Options.
• Environment variables.

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

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.