--- title: "Gateway Setup Editor" description: "" url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/configuration/gse_user_guide/index.html" --- ## Introduction Gateway Setup Editor (GSE) is a standalone Java and C++ application which allows you to edit the setup of the Gateway. This document is a reference guide which will step you through the major components. This document assumes the user has a basic understanding of the Geneos framework. It guides you through the fundamental principles behind the GSE interface and its main components. ## Licensing The GSE is part of the Geneos Framework. If you have a licence for Geneos you can deploy as many GSE's as you like within the group or organisation that has the licence. ## Glossary of terms
Term Description
GSE Gateway Setup Editor.
Named item Refers to any item in the setup that can be named, and referred to. Examples include Probes, Samplers and variables.
GA Version General Availability. Geneos products that are in Beta or production are said to be GA's. They have been tested internally by ITRS.
RA Version Restricted Availability. Geneos products that have not been tested, and are considered pre Alpha
## General Overview ### Starting Gateway Setup Editor There are two ways to start the Gateway Setup Editor (GSE): - [Standalone](#standalone) - [From the Active Console](#from-the-active-console) #### Standalone Note:  Beginning Geneos 5.5.x, the Managed Entity display name is used in the user readable paths throughout the Gateway Setup Editor, except when the GSE is opened as a standalone application. This only applies if you open the GSE within the Active Console. To start the GSE standalone, run the `GatewaySetupEditor.exe` located in the directory you installed or unzipped the files in. There are a number of start-up flags and settings you can define which modify the behaviour and configuration of the GSE while it is running. These settings are configured by modifying the `GatewaySetupEditor.gci` file that resides in the same directory as the `GatewaySetupEditor.exe`. For a complete list of these flags, and details of how to change this file, see [Start up settings](#start-up-settings). On Windows, the GSE uses a single `GatewaySetupEditor.gci` regardless of whether the GSE is opened from the Active Console, or as a standalone application. On macOS, the GSE uses two separate `GatewaySetupEditor.gci` files: - If opened from the Active Console, the GSE uses the `GatewaySetupEditor.gci` from the Active Console directory. - If opened as a standalone application, the GSEuses the `GatewaySetupEditor.gci` from the Gateway Setup Editor directory. #### From the Active Console The GSE can run from within the Active Console. To launch the GSE without opening a setup, go to **Tools > Gateway Setup Editor**. To open an existing Gateway configuration, use one of the following methods: - Select **Configure gateway** from the toolbar, then select a Gateway and press **OK**. - Right-click a Gateway and select **Configure gateway**. - Double-click a Gateway in the Gateways view. When you run the GSE from the Active Console, it adopts all the arguments passed to the Active Console from the `ActiveConsole.gci` file. The GSE can be configured to launch as a separate process from the Active Console using the **Gateway setup editor as a separate process** advanced setting. See [Workspace settings](https://docs.itrsgroup.com/docs/geneos/7.11.0/visualization/active-console/configuration/workspace-settings/index.html#general-settings). ### Open, save, and close Gateway setups Gateway setups can be edited in two modes: - From disk. - Via a Gateway. #### Open Gateway setup files from disk Gateway setup files are XML files, and can be opened from any accessible file location. To do this , go to File > Open or use the 'Open Document' button on the toolbar, and select a path using the file open dialog. Alternatively, you can Drag and Drop a file from external programs, such as Windows Explorer. **Note** Files edited from disk do not benefit from Gateway related features, such as Gateway validation and file locking. The setup is also not applied to the Gateway automatically. #### Open Gateway setups via a Gateway When running the GSE standalone you can open a setup directly via a Gateway connection. The GSE can request the setup from a Gateway for editing, and then send the setup back to the Gateway to be applied. To open a Gateway setup, you must connect to the Gateway: 1. Go to **File > Connect**, or click the **Connect to Gateway** on the toolbar. This opens the connection dialog. 2. Use the drop-down to select the Logon type. 3. In **Host**, enter the host or IP address of the Gateway. 4. In **Port**, enter the port of the Gateway. 5. If it is a secure connection, tick the box by **Secure**. 6. Press **OK**. The editor attempts to connect to the Gateway and requests the setup. If successful, a new Gateway entry is added to the Gateways view. To remove a Gateway connection, see [Removing gateway connections](#removing-gateway-connections). #### Save and close setups ##### How to save a setup To save a setup, do any of the following: - Go to **File >Save** in the menu. - Press **Save current document** on the main toolbar. - Press `Ctrl`+`S` on your keyboard. Before saving the document, the editor performs a Schema validation (See Error's view). If there are any errors, you will see this dialog: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-gse-confirm-save-dialog.png) - If you select **Yes**, the document is saved. - If you select **No**, the save is cancelled. **Note** If the setup has not been changed the save button and menu item remain inactive. To save a copy of the setup to disk, use either **File > Export** or **File > Save As**. See [The menu structure](#the-menu-structure) for more information. ##### How to close a setup To close a setup, do any of the following: - Select **File > Close** in the menu. - Right- click on the document tab and select **Close**. - Press `Ctrl`+`F4` on your keyboard. If a setup has been changed, this dialog appears on the screen: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-save-changes-dialog.png) - If you select **Yes**, the document is saved and then closed. - If you select **No**, the document is saved, and any changes are discarded. - If you select **Cancel**, the document remains open. ### The Application window An example of the main application window is shown in below: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-gse-window.png) There is a menu and a tool bar, the contents of which are detailed below. It also has a set of components which are used to view and manipulate the contents of gateways setup files. All the components reside in dockable frames (see section [Gateway Setup Editor](#general-overview)) which can be dragged around the application window or undocked (floated in their own window) The list of components in the GSE is detailed in section [Gateway Setup Editor](#general-overview). At any given time only a single dockable component is selected. This is indicated by giving it a different colour heading to the other visible components. ### The status bar The status bar (at the bottom of the main application window) displays the build number (version) of the GSE, and the schema version when a document is active. ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-schema-version.png) ### General interface standards and conventions This section outlines some general standards and tips and tricks in the GSE interface. Beginning Geneos 5.8.x, the undo and redo key functions, `CTRL + Z` and `CTRL + Y`, are supported in Active Console and Gateway Setup Editor for the following: text fields, multiline texts, and editable drop-down fields. #### The menu structure The following menu options are available in GSE: - **File** - **New** — Create new setup file. - **Open** — Open an existing setup file from disk. - **Close** — Close the current setup file. - **Connect** — Connect to a Geneos Gateway. - **Save** — Save the current file. - **Save as** — Save to a new location on disk and continue editing that file. All passwords that are not plaintext are removed from the saved file. This drops the current Gateway connection. - **Replace contents** — Replace the active document with the contents of another setup from disk. - **Reload** — Reload the current document. This will revert to the last save point. - **Load all includes** — Load all the included files, except for disabled remote include files. - **Load running setup** — Open a read-only copy of the current setup of the connected Gateway in a new editor tab. - **Exit** — Exit the setup editor. * **Edit** - **Copy** — Copy the current selection in the navigation. - **Paste** — Paste a previously copied item into the current selection in the navigation. - **Rename** — Rename the current selection in the navigation (Named items only). - **Delete** — Delete the current selection in the navigation. - **View** - **Show/Hide empty sections** — Toggles the 'show' mode of the navigation tree. - **Back** — Moves back in the navigation tree history. - **Forward** — Moves forward in the navigation tree history. - **Search results** — Shows the Search results dockable. - **Errors** — Shows the errors dockable. - **Navigation** — Shows the Navigation dockable. - **Schema** - **Switch...** — Switch the schema for the current document to a specific schema. - **Switch to working schema** — Switch to the 'working' schema, after having used 'Switch schema'. - **Tools** - **Search** — Opens the search dialog. - **Advanced Search** — Opens the advanced search dialog. - **Validate** — Validates the current document. - **Lock**\* — Sends a request to lock the current document. - **Force Lock**\* — Sends a request to force lock the current document. - **Unlock**\* — Sends a request to unlock the current document. - **Force Unlock**\* — Sends a request to force unlock the current document. - **Get Lock information**\* — Sends a request for lock information about the current document. - **Add Self Announce Probes** — Adds the Self Announcing Probe in the navigation dockable. **Note** These items are only available when editing a file through a Gateway connection. - **XML Editor** - **Format**\*\* — Format the XML - **Revert**\*\* — Revert the XML to the first state - **Find...**\*\* — Show the find dialog for the XML Editor - **Apply**\*\* — Apply the XML to the document **Note** These items are only active when an XML Editor is enabled. - **Help** - **Geneos Online Documentation** — Opens a browser window and takes you to the online documentation. - **About** — Launches the 'About' dialog. From this you can also create a diagnostic file to send to ITRS Support in the case of problems. See section [Start up settings](#start-up-settings). ### The Toolbar The toolbar contains the functions: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-toolbar.png) - **New document** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/newdocumentS22x22.png "icon") - **Open document** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/opendocumentS22x22.png "icon") - **Save current document** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/save16x16.png "icon") - **Validate current document** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/validate22x22.png "icon") - **Search** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/search16x16.png "icon") - **Delete selection** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/unreachable12x12.png "icon") - **Back** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/arrowLeft22x22.png "icon") - **Forward** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/arrowRight22x22.png "icon") - **Show/Hide the empty sections in the navigation tree** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/showEmpty22x22.png "icon") - **Lock the current document** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/lock22x22.png "icon") - **Unlock the current document** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/unlock22x22.png "icon") - **Get lock information on the current document** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/lockinfo22x22.png "icon") - **Format XML** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/format22x22.png "icon") - **Revert** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/revert22x22.png "icon") - **Find** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/find22x22.png "icon") - **Apply** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/apply22x22.png "icon") - **Create a new named item** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/createItem22x22.png "icon") ### Component List The GSE is composed of a number of components (or views). They can be accessed via the View menu in the application menu bar. Each component is contained in its own dockable frame (see section [Gateway Setup Editor](#general-overview)). The available components are summarised here, and discussed in detail in the following sections: 1. **Navigation** - Shows the main sections and items in the setup, and controls the Settings editor of the current document 2. **Errors View** - Shows a list of validation errors for the current document 3. **Search Results** - Shows the search results for the last executed search 4. **Gateways View** - Shows any connected gateways 5. **The Document Area** - Shows all the open documents 6. **Settings Editor** - Shows the selected section for editing ### Icons and colours The GSE uses icons to represent various types of data in a setup:
Named Item Section Icon Icon
Probe Probes gse47

Managed entity Managed entities gse49

Type Types gse104
Sampler Samplers gse48

Action Actions gse105
Command Commands gse106
Schedules command Schedules commands gse107
History period Rules gse108
Rule Rules gse109
Active time Active times gse110
Table Database logging gse111
Item Database logging gse112
User Authentication gse113
Group Authentication gse114
Environment Environments gse115
Audit output Audit outputs gse116
URL template Knowledge base gse117
KBA set Knowledge base gse118
FKM Table Static variables gse119
GL-names Static variables gse119
RMC templates Static variables gse119
## The Navigation Dockable The navigation view is the main interface for moving around setups. ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-navigation-dockable.png) ### Navigation icons The navigation uses icons to indicate the state and type of parts of the setup.
Icon Description

Indicates a section that exists in the setup
gse46 Indicates a section that has not been created

Indicates a 'Named item'. Examples of named items are detailed in the 'Glossary of terms'
### Modify the setup using the navigation #### How to create sections To create a section that has not been created, click **Actions > **New Action** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/play22x22.png "icon")** in the Navigation section. #### How to create named items Named items can be created in many different sections in the setup. To create a named item, right- click on a section to show the context-sensitive menu. Select the type of item you wish to create. The items will be added at the bottom of the section, and the item will be loaded into the settings editor. #### How to change the name of named items To change the name of a named item, you can do any of the following: - Right-click on the item and choose **Rename**. - Double-click the item. - Select the item and press `F2`. The item text will become editable, and the text can be changed To commit the changes you have made, press `Enter` , or click somewhere else in the editor. To revert the change, press `Escape` on keyboard. #### How to change the order of named items Named items can be moved within each section. To move an item up or down, right click on the item you wish to move, and select **Move up** or **Move Down**. Alternatively you can use `Alt`+`↑` or `Alt`+`↓` respectively. You can also sort named items alphabetically in a section, by right clicking on a section and selecting **Sort -> Ascending** or **Sort -> Descending**. #### How to delete sections and named items To delete any section, you can do any of the following: - Right-click on the item and select **Delete**. - Press the **Delete selection** button in the toolbar. - Press `Delete` on your keyboard. **Note** This will delete the section and all the items inside the section. #### How to move named items The order of the sections is fixed, however 'Named Items' can be moved around in the setup within each section. Some named items can be moved within a section or to other sections by using drag and drop: 1. Drag the item in question to the target section. If the item cannot be moved to the section, the cursor changes to indicate the move is not permitted. 2. If you drag using the right mouse button, you are presented with a context menu when you release the button: 3. Select **Move Here** to move node, or **Cancel** to abort the move. #### How to copy named items There are several ways to copy named items within a section or to other valid sections: 1. Clicking using your mouse: 1. Right-click the item and select **Copy**. 2. Right-click on the target location and select **Paste**. **Note** **Paste** only shows if the target location is valid for the copied item. 2. Dragging and dropping using your mouse: 1. Drag the item in question to the target section using the right mouse button. - If the item cannot be copied to the section, the cursor will change to indicate the move is not permitted. 2. Select **Copy Here** to copy the item, or **Cancel** to abort. 3. Using your keyboard: 1. Select the item you wish to copy, and press `Ctrl`+`C`. 2. Select the target node and press `Ctrl`+`V`. When copying a Named item as a child of the same parent, the editor changes the name of the new item to 'Copy of ' where is the name of the item being copied. If the item is being copied to a different parent, the 'Copy of' prefix is not used. If this name already exists, the editor appends a number on the end (1, 2, 3 etc) until it finds a name that is not in use. **Note** The option for Move Here does not appear if you are dragging a named item to its immediate parent. #### How to copy named items via the system clipboard When you right click a named item, there is also a **Copy XML** option. This copies the XML representation of the item (as you would see in the XML editor) to the system clipboard. This is the same as if you opened the item in the XML editor, pressed `Ctrl`+`A` (Select All), and then `Ctrl`+`C`. You can also do this by selecting an item and pressing `Crtl`+`Shift`+`C`. If the system clipboard contains well-formed XML representing a single named item and you select a section or item that is a valid parent for that item, the right-click menu contains a **Paste XML** item and the `Ctrl`+`Shift`+`V` keyboard shortcut is enabled. If you use the **Paste XML** menu item or `Ctrl`+`Shift`+`V` shortcut, a named item will be created using the clipboard content. If the name specified for the item in the XML already exists, a number will be appended to make the name unique. If the XML used contains errors (well-formed XML but not valid according to the schema), these will be indicated in the same way as if invalid XML had been entered into the XML editor. **Note** **Copy XML** and **Paste XML** are only provided for named items, not for top-level sections such as 'Samplers' or 'Rules'. You can only copy or paste one item at a time as XML. The XML which is copied and pasted is a single element, not a complete XML document - it does not start with ``. #### How to disable and enable named items Named items in the setup can be disabled. When a named item is disabled, the Gateway ignores it. Disabling named items allows you to remove it from the setup without deleting it. To disable an item in the navigation, right-click on the item and select **Disable**. Alternatively, select the item and press `Ctrl`+`D` on the keyboard. To enable an item in the navigation, right-click on the item and select **Enable**. Alternatively, select the item and press `Ctrl`+`D` on the keyboard. Disabled items are displayed as strikethrough text in the Navigation section: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-disabled-items.png) #### How to re-encrypt AES passwords encrypted with a previous key file If the main setup or some include files still have AES passwords that were encrypted with the [previous key file](https://docs.itrsgroup.com/docs/geneos/7.11.0/security/access-controls/gateway_secure_passwords/index.html#change-a-gateway-key-using--previous-key-file) of the Gateway, then you can do the following to replace these AES passwords that are encrypted with the Gateway current key: - To re-encrypt AES passwords in the main setup, right-click **Gateway** in the topmost level of the navigation tree, then select **Re-encrypt AES passwords**. ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gse-images/re-encrypt-main-gateway.png) - To re-encrypt AES passwords in an include file, [load the include file](#loading-an-include-file) if it has not been loaded yet, then right-click **Gateway** under the include file, then select **Re-encrypt AES passwords**. ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gse-images/re-encrypt-include-gateway.png) Re-encrypting the AES passwords in the main setup or in an include file will update the loaded document in the GSE and it can then be validated and saved using the normal GSE functions. **Note**  The **Re-encrypt AES password** option will only appear in the context menu if the Gateway is run with the `-previous-key-file` option. ### Password removal on copying When copying named items, any passwords (for example, within Sampler or Type definitions) are removed from the copy. This includes any of the following methods: - Right-clicking an item and selecting **Copy**. - Right-clicking an item and selecting **Copy XML**. - Dragging and dropping an item with the right mouse button and selecting **Copy Here**. - Using `Ctrl`+`C` on your keyboard. The methods above usually result in validation errors until each password is re-entered, or the password setting is removed from the copied item. Passwords are not removed when an item is moved by any of the following methods: - Right-clicking an item and selecting **Cut**. - Dragging and dropping an item with the left mouse button. - Dragging and dropping an item with the right mouse button and selecting **Move Here**. - Using `Ctrl`+`X` on your keyboard. ### Other Navigation features #### Quick Filter The quick filter allows you to hide items, or filter them out. To enable the quick filter, right-click on the navigation and select 'Quick Filter'. The filter appears at the top of the component: Simply type some text into the text field, and the tree will be filtered according to the text: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-navigation-quick-filter.png) The tree will hide any items that do not match the text and do not contain any items that match the text. Items that do match will be in bold. To disable filtering, press the red cross button to the left of the filter, or right click on the tree and select 'Quick Filter'. **Note** The tree becomes read only when filtering is enabled; you will not be able to change, move or delete any items in the tree. #### Error Highlighting When you perform a validate command (See [Errors Dockable](#the-errors-dockable)), the location of the errors will be highlighted in the navigation: Any node highlighted indicates an error in that section, or an error in some child section. In the above diagram, 'ProbeWithErrors' has an error, so all of its parent nodes are highlighted. ## The Errors Dockable The Errors Dockable lists validation errors generated by the GSE, Gateway, and Centralised Configuration. To generate a list of errors, either: - Select **Tools > Validate**. - Click **Validate current document** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/validate22x22.png "icon") in the toolbar. Saving the current document also runs the validation process. ### Error types There are three types of errors:
Type Icon Description Example
Warning

Indicates that a part of the setup may be invalid, but the problem is not serious enough to prevent other parts of the setup from working. Appears when you create a managed entity with no samplers.
Error

Indicates an error in a section that might prevent this section from working correctly. Appears when you create a managed entity without specifying the probe that it should run on.
Critical

Indicates an error that will prevent the whole setup from working. Appears when you create a malformed XML in the XML editor.
### Validation types There are two types of validations that the Gateway Setup Editor performs:
Validation type Description
Schema validation These are errors validated against the schema. The schema includes information about data types, but not relationship between sections. This is a type of validation that always occurs.
Gateway validation

The Gateway processes the setup and generates errors based on the data. This includes checking the relationship between sections.

This type of validation occurs when:

  • Editing a setup through a Gateway connection.
  • Validation is triggered from the Gateway Hub.
### The error table The errors are displayed in a table format. The list contains all errors including the errors generated by Centralised Configuration which can be filtered out.
Filter Description
Follow selection When you navigate between sections in the Navigation tree, only the errors applicable to that section or item are displayed.
Merge duplicates Merges all duplicated errors that come from multiple sources. This is applicable when Central Configuration is used and validation is carried out across multiple sources.
Connected Gateway only

Only shows the errors for the locally connected Gateway.
![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-errors-table.png) To find and resolve these configuration errors, you can double-click an item in the list which opens the relevant section in the navigation and loads the section in the settings editor. This highlights any potential errors in the setup. For example: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-error-in-managed-entity.png) #### Filtering errors You can apply three types of filters to the errors list:
Table Heading Description
Type The types of the error: warning, error or critical. For more information, see Error types.
Error A detailed description of the error.
Section

The navigation section. The icons indicate the file type and additionally:

  • Icon is displayed in colour — the file exists and is loaded in your current setup.
  • Icon is displayed but it is not in colour — the file exists in your current setup, but is not loaded.
  • No icon — he file exists in a different setup, but the error is caused by changes that have been made in your current Gateway.
Source

Indicates which validation type is the source of an error. It can be either:

  • Schema Validation — errors validated against the schema.
  • Name of the Gateway for Gateway validation. This also applies to validation triggered from the Gateway Hub. When you are using Centralised Configuration, the Gateway requests validation through Gateway Hub of any setups affected by the proposed change. These validations are indicated in the Source column by the use of Gateway Hub.

For more information, see Validation types.
Document The setup that generated the error.
## The Search Results Dockable ### Search The editor has two search features; Basic Search and Reference Search #### Basic Search To start a basic search, select **Tools > Search** or press **Search open documents** in the toolbar. This opens the following: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-editor-search.png) Type in a piece of text to search for and press **Search**, this will perform a case insensitive search of the XML. The **Scope** dropdown allows you to chose what is searched: - 'Current Document' is the initial default and means that the whole of the setup you are editing will be searched, including any open include files. - 'Current Selection' restricts the search to the section of the setup that is highlighted in the navigation pane. - 'All open documents' means that, if you are editing more than one setup (connected Gateway or directly opened file), they will all be searched. If 'Case sensitive' is checked, the exact text will be searched. If 'Regular expression' is checked, the text will be processed as a regular expression. Unless 'Include disabled items' is checked, the results will exclude items which are disabled or are contained in a section of the setup which is disabled. ### The Search Results table The search results are displayed in a table format: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-search-results.png) Double clicking on an item in list will select the relevant section in the navigation, and load the section in the settings editor. Disabled items are shown with the section names crossed out, as seen for the managed entities and alert hierarchies in the example above.
Table Heading Description
Document The document (setup) that contains the search match
Section The navigation section that contains the search match
## The Gateways Dockable The gateways view is a list of all the connections, in the form of Gateways: ![](https://docscdn.itrsgroup.com/geneos/images/active-console/ac-gateways-dockable-connection.png) You can add new Gateway connections by selecting **File > Connect**. This adds the connection and automatically open the setup. You can open a setup for a Gateway by double clicking on the item in the Gateway view. If the setup is already open, it will select it in the editor. ### Removing gateway connections When running the GSE standalone you can remove Gateway connections by deleting them. You can do this by: - Right-clicking on a Gateway in the Gateways dockable and s electing **Delete gateway**. - Selecting a Gateway and pressing `Delete` on your keyboard. ## The Document area ### Document tabs The document tabs are at the top of the central editing area: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-document-tab.png) There is a tab per each open document. Selecting a tab will bring that document to the front, and show the navigation for the document in the navigation view. To the right of the tab area there are three buttons. The left and right arrows allow you to 'scroll' the tabs along when they are not all visible. The third button shows a list of all the open documents for selection. Right clicking on a tab will present a context menu. If more than one document is open, you will see this menu:
Menu Description
Close Close the document clicked on
Close Others Close all the other documents
Close All Close all open documents
Next Select the next tab
Previous Select the previous tab
New Horizontal Group Splits the document view horizontally
New Vertical Group Splits the document view vertically
## The Setting editor The settings editor is the main area in the centre of the editor: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-sampler-editor.png) This section explains how this part of the editor is structured. ### Section Tabs The settings are normally sectioned into tabs. Although every section is different, typically there at least two tabs:
Tab name Description of contents
Basic Compulsory and commonly used settings
Advanced and Other tabs Optional settings, used less often
### Indicators Indicators are used in the settings editor to indicate if settings are compulsory or optional, and if they are in an invalid state: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-sample-indicators.png) This table explains the meaning of the indicators:
Indicator Icon Description
Compulsory

The setting is compulsory, and is in a valid state.
Compulsory and invalid

The setting is compulsory, and is in an invalid state.
Optional and not created

The setting has not been created.
Optional

The setting is optional, and is in a valid state.
Optional and invalid

The setting is optional, and is in an invalid state.
When a setting is in an invalid state, you can move the mouse over the setting to see a description of the problem: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-error-indicator.png) ### Creating and removing settings Optional settings that have not been created are shown 'greyed out'. To create the setting, either right click on the setting and select 'Create ' or simply click on the setting component or its label. The setting will change to optional. Once the setting is created, it can be removed by right clicking and selecting 'Remove or pressing the 'X' to the right of the setting. ### Table settings Some settings have multiple instances, or rows. These setting are presented in a table format. To add a row to the table, click the 'Add new' link at the bottom of the table. To remove a row, press the 'X' at the beginning of each row. ### Referencing 'Named items' Some settings reference named items in the setup (e.g. a Managed Entity *references* a Probe). These settings are always combo boxes, and they always have an arrow to the right of the combo box. To select a reference simply press the arrow to the right of the combo box and select the reference of your choice. #### Jumping to and creating referenced items To jump to a referenced item, simply click on the arrow to the right of the combo box: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-jump-to-function.png) In some situations you may wish to create a new referenced item from this component. To do so, simply type in a new name (one that is not in use for this type), and press the arrow. You will be presented with a dialog to create the new item. ### Data/Variable settings Some settings can be Data or Variables. An example of this is the Sample interval of a managed entity: The interval can either be data (an integer value in seconds) or a variable value (which must also be an integer type) Data/Variable settings always have data or var link directly after the label and before the component: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-data-variable-settings.png) The link acts a toggle, switching the component between a data and a variable. A variable setting is reference to a named item elsewhere in the setup (See Referencing 'Named items') ### String variable settings String variable settings are a mixture of string constants, and variables. String variable settings always consist of a text field, and drop down menu with all the variable values inside. The Gateway will substitute the variables at runtime, and concatenate the values together. Example: Define two variables: ``` Variable 'var1', Type: Integer, Value: 10 Variable 'var2', Type: Boolean, Value: true ``` String variable value in editor: ``` The value of var1 is $(var1), and var2 is $(var2) ``` The Gateway substitutes the values, giving the final string: ``` The value of var1 is 10 and var2 is true ``` ### Comments Comments can be added to any top level entity in the Navigation window To create a comment: 1. Right click on the target component and select **Create comment**. 2. This will create the **Comment for ``** window. 3. You can now type the comment text. Click **OK** to add the comment or **Cancel** to exit without saving. Comments are displayed at the top of the **Editor** window. ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-add-comment.png) To edit a comment, right click on an entity with a comment and click **Edit Comment** or **Remove Comment**. You can still add XML comments to any node by switching to XML mode. If XML comments are present, a message is displayed below the comment box in the form: ` additional comment(s) in XML`. If you have updated from an older version of Gateway Setup Editor which allowed comments to be attached to individual configuration options then existing comments will still be available from the XML editor. ### Getting Help To get help for a setting, right click on the setting and select **Help**: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-getting-help.png) The GSE opens a browser window and takes you to the Geneos online documentation for the setting. The version of the help accessed corresponds to the schema version, not the GSE version. If you do not have readily available internet access, you can also download the Geneos documentation for your version and configure the GSE to point at this downloaded version instead. See [Host the documentation locally to use GSE context-sensitive help](#host-the-documentation-locally-to-use-gse-context-sensitive-help). Note: We recommend that you always use the online documentation where possible, as it contains the most up-to-date information. ### XML editor The XML editor allows you to edit the underlying XML of the setup, bypassing the standard user interface. To start the XML editor for section, select the section in the main navigation, and then select XML from the combo box at the top right of the setting editor: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-xml-editor.png) The XML editor has several functions, all of which are available from the main toolbar, the XML editor menu, or using the context menu by right clicking in the editor. These functions are:
Function Description
Format Formats the XML according to a predefined style.
Revert Reverts the XML text to the state it was in when the editor was enabled.
Find Shows a find dialog for performing text searches in the editor.
Apply Applies the current XML to the editor.
Once you have finished editing the XML, you should apply it to make sure the changes are valid. You can apply the changes by pressing 'Apply' on the main toolbar, or switching back to normal mode using the combo box at the top right of the setting editor. If the XML is invalid, you may see this dialog: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-xml-error.png) You must fix the error before you can save the setup. #### Find function in XML editor In the Find dialog, you can use wildcards or regular expressions in your searches. To do this, tick the **Use** box and select Regular Expressions (default) or Wildcards. You can then use the button to the right of the search box to add regular expressions or wildcards to your searches. After pressing **Find**, click on the XML editor and use `F3` to cycle through your matched items in a search. ### Rule editor The Rule editor is the text area at the bottom of a rule: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-rule-editor.png) The rule editor is a syntax highlighting code editor, for the 'Geneos' language. #### Templates and Code assistance The editor has some predefined templates to assist you. To use a template, right-click the editor and then select **Templates**. The code will be inserted at the cursor position in the rule editor. The templates are not complete; they require you to modify the code with appropriate values. #### Fixing errors If your rule code contains errors you will not be able to save the setup. You must fix any code errors first. Errors are indicated in two ways in the rule editor: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-rule-editor-error.png) Errors are underlined in the text, and they are indicated in the error bar on the right hand side. ## Refactor Refactoring allows you to globally change the name of a 'named item', and all of its references. To start refactoring, right click on a 'name item' in the navigation and select 'Refactor'. Alternatively, right click on the name setting in the setting editor and select 'Refactor'. The Refactor dialog will open: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-refactor.png) The dialog is made of two parts; the new name and the items that will be changed. To perform the refactor operation, change the name in the 'New name' field, then select the items you wish to change in the list at the bottom of the dialog. Finally press the 'Refactor' button. You should see the dialog change. It now displays the number of items that have been refactored. You can see an example below: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-refactor-enabled.png) The Refactor dialog will remain open, in case you wish to rename the items again. Press the 'Close' button to dismiss the refactor dialog. ## File Locking Gateway has file locking mechanism's which can be accessed through the Gateway setup editor. These features are only available when editing a setup through a gateway connection. ### Obtaining and releasing a lock To obtain a lock select **Tool > Lock**, or click the **Lock the current document** in the toolbar. If the lock is unsuccessful, then it means that the file is already locked. **Note** You cannot obtain the lock twice! If the lock failed you can find out who has the lock by getting lock information (See 'Getting lock information'). If the lock has failed because another user already has the lock, you can Force lock (Tools->Force lock). This will remove the current lock (if any), and obtain the lock. To release the lock select **Tools > Unlock**, or press **Unlock the current document** in the toolbar. If the unlock is unsuccessful, an error will be displayed. You cannot unlock if you do not own the lock, or the file is not locked. ### Getting lock information At any time you can get lock information for a setup. To get lock information, select Tools->Get lock information, or press 'Get lock information on the current document'. You will see a dialog like this: Lock information:
Name Description
MainSetupFile Yes, if the lock is on the main setup file. No if it is an 'include' file.
Locked Yes if the file is locked, No if the file is not locked.
ConnectionId The internal connection id.
GatewayId The gateway id.
Username The username of the user who locked the file. ActiveConsoleX indicates an anonymous logon.
Workstation The Hostname or IP address of the workstation that got the lock.
LockedTime The date and time the lock was obtained.
### Losing the lock It is possible for another use the **Force Lock** a file. This removes and overrides the current lock, if there is any. ### Autolock When a Gateway is started, it is possible to specify a parameter such that the GSE will automatically take the lock if connected to the Gateway. To start the gateway in this mode, launch it with the `-autolock` parameter. With the autolock feature running, if the GSE connects to the main setup for the running gateway and the lock is available, it displays that the document has been automatically locked. If you decide to keep the file locked, the Gateway Setup Editor will load the main setup and will display a message next to the top level to indicate that it is now locked, as illustrated below: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-navigation-locked.png) If the GSE attempts to connect to a running gateway with the autolock feature active, and the lock is not available, it will load the setup but will display a message against the top level to show that it is already locked by someone else. **Note** If gateway authentication is not in use, a more generic message may get displayed such as "Locked by Active Console". In this state, the user does not have the lock, and will be unable to write any changes back to the gateway server. However, if you leave the GSE in this state, and the lock subsequently gets released by the other user who was holding it, the fact that the lock is now available will get automatically detected. While the main setup has become unlocked, and you reload and lock it again, then the main setup will be reloaded and they will have the lock for it. Autolocking works in the same way for [Include Files](#include-files). With the autolocking feature active, when the user clicks on an include file to load it, the lock will automatically be taken if it is available. A message will now be shown next to the include file setup to indicate that it is now Locked. If, however, another gateway also shares this include file, and a GSE connected to that gateway has already taken the lock on the include file, when the user attempts to load the include file it is still loaded but the user does not get the lock. In this state, the user does not have the lock on the include file, and will be unable to write any changes made to the include file back to the gateway server. **Note** The user does still have the lock on the main setup file. The user can still make changes to the main setup file and save them back to the gateway server, they are only restricted from changing the include file. Having made changes to the main setup, when the user tries to save the changes, gets a notification that either you do not have a permission, or the file is locked by another user. If the lock on the include file is initially held by someone else, but the other user who was holding the lock subsequently releases it, the fact that the lock is now available will get automatically detected, and the include file will be reloaded and they will have the lock for it. ## 'Include' files Gateway 2 allows you to 'include' multiple files into the main setup. The files are merged by the gateway to produce the overall setup. ### Creating an include file To create an include file you must first create the 'Includes' section. Click on includes in the navigation section. To create an include file, right click on Includes, and select 'New Include'. An include file is not a 'named item'. The text in the 'name' is actually its location, or path. Type in the path to a file in the location field: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-include-setup.png) **Note** The path is relative to the main setup file location. ### Loading an include file Included files are not automatically loaded as part of the main setup. To load a setup, you must expand the include node in the navigation tree, and click on the node Click to load. ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-include-load-file.png) If the main setup file was loaded from a gateway connection, the editor will request the include file from the Gateway. If the file was loaded from disk, the editor will attempt to load the include file from disk. Once the include file is loaded, the structure is the same as the main setup file, and editing is performed in exactly the same way. ## Schema ### What is a schema? A schema is an XML document that describes the content of another XML document. In the case of the GSE, the schema describes the settings that can be configured for the Gateway, along with any Netprobe and Plug-In configuration that is sent to Netprobes. The GSE reads the schema, and uses it to construct the GUI. This is presented to the user in two places; the navigation and the settings editor. A change in the schema can result in the structure of these components changing. The schema also contains restriction information, enabling the GSE to validate the input, and provide useful feedback to the user. A full description of XML Schema is beyond the scope of this manual. For comprehensive description, please refer to **Note** The link for the schema in the XML file, such as `http://schema.itrsgroup.com/GA7.7.1-251203/gateway.xsd`, is provided to uniquely identify the schema. The schema is not available for download from a public website. The Gateway schema can be retrieved through the following ways: - By running the Netprobe with the [`-extract` command-line option](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/netprobe-command-line-options/index.html#binary-command-line-options) to write the embedded Gateway schema to a file. For example, on Linux 64-bit: ``` netprobe.linux_64 -extract schema gateway.xsd ``` Replace `gateway.xsd` with the path or filename where you want to save the schema. On other platforms, use the appropriate Netprobe executable (for example, `netprobe.exe` on Windows). - By retrieving the schema from the Gateway over HTTP: ``` http://:/schema/ ``` Access to the `Schema Debug` webpage can be controlled by configuring **operatingEnvironment** > **httpConnectionRequirements** > **internalData** settings in the Gateway Setup Editor. ### Schema versioning Schemas in the Geneos system are versioned using the same convention as all other Geneos components: ``` - ``` e.g.: GA-091212 The GSE ships with the latest version of the schema at the date of release, which it uses to create new setup files. Each setup file contains a reference to the schema version and the GSE then uses that working schema version for editing the setup. When connected to a Gateway, GSE will use the schema version that the Gateway uses, however this version may change if the Gateway gets upgraded. If the schema in GSE is upgraded, new settings might become available, as well as some settings may be hidden due to deprecation. It is recommended to use the version that the Gateway uses. Once GSE has obtained the latest available version from the Gateway, it will use that version when creating new setups. #### Determining Schema Version The schema version for the active document is displayed in the status bar at the bottom right of the GSE window. The version status bar can be in these states:
State Example Status bar Description
Normal gse93 The document is using the working schema
Alternate schema gse94 The document is using an alternate schema, i.e. a schema loaded from disk by the user
Incorrect schema gse95 The document is using a different version of the schema than the one specified
If you move the mouse over the schema version, a tooltip will give you extra information. #### Switching to Alternate Schema In some scenarios it may be necessary to switch to an alternate schema. To do this, go to Schema -> Switch…. You must pick a valid schema from the file chooser. The status bar will change to indicate that you are using an alternate schema. At any time you can switch back to the working schema by choosing Schema->Switch to working schema. #### Loading Setup with Alternate Schema If you load a setup that was previously saved using an alternate schema, either by you or by another user, then GSE will offer to choose between the current and that special schema. ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-loading-schema.png) If the alternate schema is unknown to GSE, it will ask the user to locate that schema on the disk. This can happen if the schema was edited by another user. #### Gateway Schema Change The gateway will publish its current schema version, however it may change if the Gateway or a Probe connected to that Gateway is upgraded. If the schema changes while the Gateway's setup is being edited, GSE will show a notification and will offer to load the new schema. #### Deprecated settings When GSE schema is upgraded, some settings may be hidden due to deprecation unless they already have a value. To view all the deprecated settings anyway, choose View > Show deprecated. All such settings will be marked with a warning sign. ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-deprecated-setting.png) ## Start up settings There are a number of startup flags and settings you can define which modify the behavior and configuration of the GSE while it is running. These settings are configured by modifying the GatewaySetupEditor.gci file that resides in the same directory as the GatewaySetupEditor.exe. This file is a text file, so can be edited in any text editor. The file that is shipped with GSE will look something like this: ``` ############################################################ #### The java class that has 'main' ############################################################ -mainclass com.itrsgroup.gse.GatewaySetupEditor ############################################################ #### The JVM to use and arguments ############################################################ -jvm .\JRE\bin\client\jvm.dll -jvmargs Xmx128M Ddocking.floatingContainerType=frame ############################################################ #### Misc ############################################################ #The jvm depends upon dll's in this directory (e.g. msvcr71.dll) -path JRE\bin -logexceptions -gsedir gse ``` ### The syntax The file is newline delimited; each flag starts with a hyphen. Any arguments for a given flag are again separated by a newline. Any lines that begin with '#' or are empty are ignored. ``` #comment1 -…#comment2 … ``` ### GatewaySetupEditor.exe flags See [Start Up Settings](https://docs.itrsgroup.com/docs/geneos/7.11.0/visualization/active-console/configuration/startup-settings/index.html). ## Host the documentation locally to use GSE context-sensitive help The context-sensitive help for the GSE requires internet access to connect to the Geneos online documentation. If this is not possible for your system, you can opt to download and host a copy of the documentation locally for the context-sensitive help. Note: We recommend that you always use the online documentation where possible, as it contains the most up-to-date information. ### Create a hosting folder, download and unpack the files First, you must configure a folder to act as a web server, and download and unpack the files: 1. Configure a folder on your machine to act as a web server host the documentation. - There are many methods for doing this, such as using Windows Internet Information Services (IIS) or a Python HTTP server. 2. Download the offline documentation package for your version from [Offline Documentation for Geneos](https://docs.itrsgroup.com/docs/geneos/7.11.0/offline-docs/offline-docs/index.html). - The file is called `offline-docs.GA.zip`. 3. Download the context-sensitive help mappings bundle by clicking [this link](http://dl.bintray.com/itrsgroup/techcomms/geneos-docs-zips/csh.zip). - The file is called `csh.zip`. 4. Create a folder inside the hosting folder called ``. - For example, if you downloaded the `offline-docs.GA.4.10.0.zip` package, create a folder called `4.10.0`. 5. Unpack the documentation to the `` folder you have just created. 6. Unpack `csh.zip` to the hosting folder. - This creates a folder called `csh`. **Success** You now have a folder set up to host the documentation, and inside this folder is a `csh` folder and a `` folder. ### Configure your Active Console and GSE .gci files After you set up your host for the documentation and add the files, you must configure your Active Console and Gateway Setup Editor .gci files: 1. Open the `ActiveConsole.gci` file in your `ActiveConsole2` folder. 2. Find the `-cshHost` setting in the file. 3. Modify the value of the setting to location of the folder hosting the documentation. - For example, if the folder is configured on the local machine on port 12345, then the setting is `http://localhost:12345`. 4. Save the file. 5. Open the `GatewaySetupEditor.gci` file in your `ActiveConsole2` folder. 6. Repeat steps 2–4 for this file. These settings take effect upon restarting the Active Console. **Success** Right clicking on **Help** on a setting in your GSE opens a browser window and takes you to the locally hosted documentation. We recommend you periodically update both your documentation bundle and mappings bundle from our website to keep up-to-date with the latest documentation changes. ## Troubleshooting To view the frequently asked questions in Geneos, see [ITRS Support](https://support.itrsgroup.com/hc/en-us/categories/115000687225-Geneos-Self-help) website. ## Reporting faults and suggesting enhancements If you experience problems with the Gateway Setup Editor, or have suggestions for improvement, please contact the [ITRS technical support team](https://support.itrsgroup.com/). When submitting a ticket, please attach the diagnostics file to help us identify your issue. To generate this file, follow these steps: 1. Select **Help > About** on the menu in the GSE. 2. Click **Create diagnostic file**. 3. Select where you would like to save the file and enter the file name. 4. Click **Save**. If successful, the Created diagnostics window opens.