Skip to content

Commit

Permalink
Add: Document GSA settings in README
Browse files Browse the repository at this point in the history 
These settings were documented externally before and should be put into
the GSA repository now to have same at the same location as the code.
  • Loading branch information
@bjoernricks
bjoernricks committed Oct 10, 2023
1 parent 59239c1 commit c8db553
Showing 1 changed file with 181 additions and 2 deletions.
183 changes: 181 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,25 @@ written in [React](https://reactjs.org/).
- [Releases](#releases)
- [Installation](#installation)
- [Developing](#developing)
- [Settings](#settings)
- [Config File](#config-file)
- [Config Variables](#config-variables)
- [vendorVersion](#vendorversion)
- [vendorLabel](#vendorlabel)
- [guestUsername and guestPassword](#guestusername-and-guestpassword)
- [disableLoginForm](#disableloginform)
- [enableStoreDebugLog](#enablestoredebuglog)
- [logLevel](#loglevel)
- [timeout](#timeout)
- [apiServer](#apiserver)
- [apiProtocol](#apiprotocol)
- [manualUrl](#manualurl)
- [manualLanguageMapping](#manuallanguagemapping)
- [protocolDocUrl](#protocoldocurl)
- [reloadInterval](#reloadinterval)
- [reloadIntervalActive](#reloadintervalactive)
- [reloadIntervalInactive](#reloadintervalinactive)
- [reportResultsThreshold](#reportresultsthreshold)
- [Support](#support)
- [Maintainer](#maintainer)
- [Contributing](#contributing)
Expand Down Expand Up @@ -95,8 +114,7 @@ opened at the URL `http://127.0.0.1:8080`, containing the GSA web application.
When a JavaScript file of GSA in the src folder is changed, the browser window
will reload automatically.

Besides the development server [gsad](https://github.com/greenbone/gsad/) needs
to be running with CORS enabled.
Besides the development server [gsad] needs to be running with CORS enabled.

```sh
gsad --http-cors="http://127.0.0.1:8080"
Expand All @@ -119,6 +137,165 @@ For HTTPS only the protocol property must be `'https'` accordingly.
After changing the `config.js` file, the browser window should be reloaded
manually.

## Settings

The behavior of GSA can be changed via settings. All of the settings can be
adjusted via a config file. Some of the settings can be changed during runtime
too. Some of them are persistent during reload, some are reset during reload.

This sections lists all settings and explains their behavior.

### Config File

The config file is a normal JavaScript file (with a .js suffix). It is named
`config.js` and will be loaded from the `/usr/share/gvm/gsad/web/` (or
`/usr/local/share/gvm/gsad/web/`) directory when using [gsad] for providing GSA
e.g. in production environments.

During development when using the on-the-fly-transpiling JavaScript development
server (via `npm run start`) the file is loaded from the `public/` directory.

The `config.js` file must contain a global config object with settings as
properties e.g.

```js
config = {
// javascript files in contrast to JSON files allow comments
foo: 'bar',
}
```

It is evaluated in the `GmpSettings` object implemented in the
[gmpsettings.js](./src/gmp/gmpsettings.js) file. The `GmpSettings` object is
instantiated once for the [GSA application](./src/web/app.js#L53)

### Config Variables
| Name | Type | Default | Changeable during runtime | Persistent after reload |
| ------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------- | ------------------------- | ----------------------- |
| [apiProtocol](#apiprotocol) | String ('http' or 'https') | `global.location.protocol` | - | x |
| [apiServer](#apiserver) | String | `global.location.host` | - | x |
| enableGreenboneSensor | Boolean | false | - | x |
| [disableLoginForm](#disableloginform) | Boolean | false | - | x |
| [enableStoreDebugLog](#enablestoredebuglog) | Boolean | false | x | x |
| [guestUsername](#guestusername-and-guestpassword) | String | undefined | - | x |
| [guestPassword](#guestusername-and-guestpassword) | String | undefined | - | x |
| locale | String | undefined | x | x |
| [logLevel](#loglevel) | String | [`'warn'`](./src/gmp/gmpsettings.js#L27) | x | x |
| [manualUrl](#manualurl) | String | [https://docs.greenbone.net/GSM-Manual/gos-22.04/](./src/gmp/gmpsettings.js#L24) | - | x |
| [manualLanguageMapping](#manuallanguagemapping) | Object | undefined | - | x |
| [protocolDocUrl](#protocoldocurl) | String | [https://docs.greenbone.net/API/GMP/gmp-22.4.html](./src/gmp/gmpsettings.js#L25) | - | x |
| [reloadInterval](#reloadinterval) | Integer | [15 * 1000; // fifteen seconds](./src/gmp/gmpsettings.js#L21) | x | - |
| [reloadIntervalActive](#reloadintervalactive) | Integer | [3 * 1000; // three seconds](./src/gmp/gmpsettings.js#L22) | x | - |
| [reloadIntervalInactive](#reloadintervalinactive) | Integer | [60 * 1000; // one minute](./src/gmp/gmpsettings.js#L22) | x | - |
| [reportResultsThreshold](#reportresultsthreshold) | Integer | [25000](./src/gmp/gmpsettings.js#L26) | x | - |
| [timeout](#timeout) | Integer | [300000; // 5 minutes](./src/gmp/gmpsettings.js#L28) | x | - |
| [vendorVersion](#vendorversion) | String | undefined | - | x |
| [vendorLabel](#vendorlabel) | String | undefined | - | x |

#### vendorVersion

Allows to adjust the shown product version string at the Login and About pages.

#### vendorLabel

Allows to adjust the product info image at the Login page. It must be a relative
path e.g. `foo.png`. The path will be mapped to `$INSTALL_PREFIX/share/gvm/gsad/web/img/`
on production (with [gsad]) and `gsa/public/img` for the [development server](#developing).

#### guestUsername and guestPassword

Both settings allow to login with a single click. This user has to be set up
carefully. E.g. if this user is created with admin privileges it will have these
permissions after login. Thus be careful when creating a guest user. If
guestUsername is contained in the `config.js` file the `Login as Guest` button
will be shown.

#### disableLoginForm

This setting allows to deactivate the username password form at the Login page.
It can be used to deactivate login for *normal* users.

#### enableStoreDebugLog

Changes to this settings are persistent during browser reload. If the value has
been changed in the browser console e.g. via `gmp.settings.enableStoreDebugLog = true`
the browser window needs to be reloaded to apply this setting. The setting can
be `true`, `false` or `undefined`.

If either enableStoreDebugLog is `true` or it is `undefined` and [logLevel](#loglevel)
is `debug` the changes of the redux store are shown. The store contains all data
visible to the user.

#### logLevel

The value of logLevel is persistent during browser reload. If the value has been
changed e.g. by running `gmp.settings.logLevel = 'debug'` in the browser console
the browser window needs to be reloaded to apply this setting. Also this setting
must be reset via `gmp.settings.logLevel = undefined` to not display the debug
logs anymore and to use the default setting again. If logLevel is set to
`'debug'` and [enableStoreDebugLog](#enablestoredebuglog) is not `false` the
store debug logs are shown too.

#### timeout

This setting specifies as timeout after a data request to our API provided by
[gsad] will fail. Default is 5 minutes (300000 ms).

#### apiServer

Defaults to `window.location.host`. It contains the domain/IP address of the
[gsad] server including the port e.g. `'192.168.10.123:9392'`.

#### apiProtocol

Defaults to `window.location.protocol` and must be either `'http'` or `'https'`.

#### manualUrl

URL to the manual. On a Greenbone Enterprise Appliance the manuals are served
locally and the value is the relative URL `'/manual'`. The URL is used for all
links from help icons pointing to a page at the user manual.

#### manualLanguageMapping

Because we could possibly have a different number of translated manuals then
available locales, a setting for mapping a locale to a corresponding translated
manual is provided. If a current locale isn't mapped it always falls back to the
English (`en`) locale.

#### protocolDocUrl

This setting contains the URL to the public Greenbone Management Protocol (GMP)
documentation. It is https://docs.greenbone.net/API/GMP/gmp-22.4.html and only
used at the About page.

#### reloadInterval

The *standard* interval for reloading data. The default is 15 seconds
(15000 ms).

#### reloadIntervalActive

This interval is used for reloading data on pages with an active process. This
is currently the case for a task list page, task details page, report list page
and report details page containing at least one actively scanning task.
The default is 3 seconds (3000 ms).

#### reloadIntervalInactive

This interval is used instead of [reloadInterval](#reloadinterval) or
[reloadIntervalActive](#reloadintervalactive) for reloading data when GSA
is not the active browser window or tab. The default is 60 seconds (60000 ms).

#### reportResultsThreshold

If the number of filtered results of a shown report extends this threshold only
the report without details is loaded and an information panel is show at the
Hosts, Ports, Applications, Operating Systems, CVEs, Close CVEs and TLS
Certificates tabs to prompt the user for lowering the number of results by
additional filtering. This setting can be used to improve the responsiveness of
the report details page.

## Support

For any question on the usage of `gsa` please use the [Greenbone Community
Expand All @@ -144,3 +321,5 @@ github](https://github.com/greenbone/gsa/issues) first.
Copyright (C) 2009-2023 [Greenbone AG](https://www.greenbone.net/)

Licensed under the AGPL-3.0 [GNU Affero General Public License v3.0 or later](LICENSE).

[gsad]: https://github.com/greenbone/gsad/

0 comments on commit c8db553

Please sign in to comment.