How do I use the debug agent?

The StormWorks kernel includes a telnet agent called "debug agent". This allows you to log in to the StormWorks kernel via telnet and run statement language expressions. This is useful when trying to test and debug statement language, and when trying to debug the behavior of the StormWorks kernel itself.

When the Entuity system is configured for SAML authentication, you will to log in to the debug agent via an Access Token. When the Entuity system is configured for other authentication modes (i.e. internal, LDAP, BMC RSSO), you can log in via standard username and password.

1. To connect to the debug agent, telnet the following to port 5465 on a machine running Entuity. You can do this from the Entuity Remote Terminal:
   

   telnet localhost 5465

2. When it connects, the first character you type determines the type of connection:
   • type 'x' if launching telnet from a Windows Command Prompt.
   • type 't' for a terminal connection. Note, 't' is the only connection type permitted when logging in via an Access Token. When using the connection type 't', you can disable local echoing of your commands by typing the command 'localEcho=0'.
     
     
3. If the Entuity system is configured for SAML authentication:
   Enter the Access Token as the password for the Entuity installation to which you are connecting. The username should be set as an empty string. When connecting using the Windows Telnet client from a Windows Command Prompt, you will also have access to an autocomplete capability by typing the tab key.
   
   If the Entuity system is configured for other types of authentication:
   Enter a username and password for the Entuity installation to which you are connecting (your Entuity credentials, not your Windows or Linux credentials). When connecting using the Windows Telnet client from a Windows Command Prompt, you will also have access to an autocomplete capability by typing the tab key.
   
   
4. At the debug agent command line, type ? and press enter to give you a list of available StormWorks functions, followed by a list of debug agent options.
   • A useful option is the multiLine option. This allows you to enter larger statement language expressions across separate lines:
     multiLine=1
   • Another useful functionality is the ability to set the current object context by setting the ID.
     • You can set this explicitly to a number if you know the ID (found via the debug agent, from the DB, from WebUI URLs, or from the StormWorks ID row in the Object Attributes dashlet of the object).
     • You can also use an expression to find the object, e.g.:
       

       id=3527
       id=simple; get_device("bottom3550")

Use the help() function to get help on functions, and also to search for whole or partial text matches. Examples of its usage include:

• help("rand")

  Returns the help entry for the function rand().

• help("stream*")

  Returns a list of all help entries whose topic starts with the string "stream".

• help("view", 1)

  Returns the list of all help entries that contain the word "view" in either their topic name or body text.

• help("*snmp*", 1)

  Returns a list of all help entries which contain the string "snmp" anywhere in their topic name or body text.

The debug agent also has an auto-complete that is available if you log in using Windows telnet from a Command Prompt:

1. Press 'tab' at the command prompt, which will automatically write simple; to start a new expression.
2. Type part of an expression and press tab to automatically complete it, if there is only one option. If there are more than one options, press tab again for a list of possible completions.