IBM Support

Common Agent Telnet commands

Question & Answer


Question

Does the IBM Rational Build Forge Agent receive commands from the Engine in a particular format? This technote provides information for the commands that can be issued in a Telnet shell for troubleshooting purposes.

Answer







EXEC

The exec command tells the agent to run something. This is the most flexible command type and is used to run step commands in the agent. This format can be modified to be any command line command you would like to use by editing the exec echo test line to be your specific command. For example changing the below that line to exec ls -la would print out a directory listing.

Explanation:

Format

Here is the format of a cmd exec:

cmd exec
exec echo test
root /tmp
tag /
dir /
timeout 300
username <user>
password <pass>
go

Breakdown
  • cmd exec

    This initial line tells the agent what to expect. In this case it will be a command which the agent will then execute. The command could be any valid command line command.

  • root

    This is the initial starting directory for the agent. The parameter usually used for this value from Build Forge is ${BF_SERVER_ROOT}, or the server's path entry with the addition of ${BF_PROJECTNAME_PHYS}.

  • tag

    This is the subdirectory off of root represented by the build tag for the run -for example BUILD_1.

  • dir

    This is a subdirectory off of root and tag which the step has specified within the directory field. Generally this is /.

  • timeout

    This controls how long hte agent will wait for the command it is executing to come back with output on STDOUT. If the timeout is exceeded the agent emits a TMO, or timeout error are kills itself. This timeout error is then captured by the console and the step is failed or set to warning depending on the continue on fail setting.

  • username

    The user name the agent will switch context to prior to running any commands

  • password

    The password for the aforementioned user

  • go

    This signals to the agent the end of the parameters for this piece. The agent will then attempt to run the command in the root/tag/dir directory. If the root/tag/dir combination does not exist the command will fail. For this reason we use a simple path in the manual test.

Agent tracing will show two additional items in a cmd exec portion:
  • lang

    The language of the user starting the build.

  • encpass

    This replaces the password field with a BF encoded password to prevent transmission of plain text passwords over the wire. This is the same format as a bfagent.exe -P <password>. You would be able to generate the password with the bfagent binary and use that after encpass in place of password to mimic the same behavior manually.

Example:

# telnet server 5555
Connected to server.ibm.com (9.9.9.9).
Escape character is '^]'.
200 HELLO - BuildForge Agent v7.0.2.0-3-0004
cmd exec
exec echo test
root C:/build
tag /
dir /
timeout 300
username build
password build
go
300 DATA s 17
ENV: =C:=C:\build
.
...(ENV Entries)...
300 DATA s 22
ENV: windir=C:\WINDOWS
.
300 DATA s 36
EXEC: start [C:\build@SERVER] echo test
.
300 DATA s 51
EXEC: Performing variable expansion on command line
.
300 DATA s 62
AUTH: Running as: [buildforge] in domain [FTW] SID Type [User]
.
300 HEARTBEAT 1
300 DATA s 4
test
.
250 RESULT 0
EXEC: end [C:\build@FTW] echo test
.
260 EOR





MKDIR

The agent runs a MKDIR command prior to executing the step commands. This helps ensure the directory exists before the cmd exec is attempted.

Explanation:

Format

Format of cmd mkdir

cmd mkdir
root c:/build
dir dir/BUILD_1
username <username>
password <password>
go

Breakdown
  • cmd mkdir

    This signals to the agent this is a special case command - make directory request

  • root

    For cmd mkdir root takes on a different meaning - it is the $BF_SERVER_ROOT path only. This path will have to be correct and exist for cmd mkdir to succeed

  • dir

    This is the combination of ${BF_PROJECTNAME_PHYS} and ${BF_TAG} and is the directory the cmd mkdir will attempt to create appending it to the root directory specified earlier.

Example:

#telnet server 5555
Connected to server.ibm.com (9.9.9.9).
Escape character is '^]'.
200 HELLO - BuildForge Agent v7.0.2.0-3-0004
cmd mkdir
root c:/build
dir proj/BUILD_1
username build
password build
go
300 DATA s 56
ENV: ALLUSERSPROFILE=C:\Documents and Settings\All Users
...(ENV Entries)...
300 DATA s 22
ENV: windir=C:\WINDOWS
.
250 RESULT 0
MKDIR: c:\build\proj\BUILD_1 already exists and is a directory.
.
260 EOR





PING

The ping command is used during a server test. This will test the user auhentication and basic agent functioning only. It will _not_ open a shell or attempt to create a directory. This means the server path will not be tested for. If the server path is invlaid it is possible to get a passed result from a server test and have an invalid configuration.

If the temp directory is not writable for the agent user then an error will be displayed stating that fact. The temp directory on UNIX is either /tmp, or the value specified in $TMPDIR. On Windows the location is in %TEMP% or %TMP%. If for some reason the agent is not able to write to these directories a cmd ping will show you.


Format

Format of cmd ping:

cmd ping
username <username>
password <password>
go

Example:

# telnet server 5555
Connected to server.ibm.com (9.9.9.9).
Escape character is '^]'.
200 HELLO - BuildForge Agent v7.0.2.0-3-0004
cmd ping
username build
password build
go
300 DATA s 48
EXEC: Locale set to 'English_United States.1252'
.
300 DATA s 62
AUTH: Running as: [build] in domain [DOMAIN] SID Type [User]
.
300 HEARTBEAT 1
300 DATA s 16
PLAT: Windows XP
.
250 RESULT 0
PING: internal loopback test complete
.
260 EOR






SYSCONF

The sysconf agent command is used for getting the built-in manifest values. One sysconf command can be used to fill in all of the built-in manifest variables making this a powerful and simple tool for using manifests. The cmd sysconf command will only be used if at least one built-in is in use. In any event adding all of the built-in variables will take the same amount of engine to agent communication to get all of the values back. The engine then fills in those built-ins specified in the collector using a filter, but it still gets all of the values from the agent. If you wish to use one built-in see if you can leverage any of the other built-in collector properties as the cost is already paid with the first variable.

Format

Format of cmd sysconf.

cmd sysconf
username <username>
password <password>
go

Example:

# telnet server 5555
Connected to server.ibm.com (9.9.9.9).
Escape character is '^]'.
200 HELLO - BuildForge Agent v7.0.2.0-3-0004
cmd sysconf
username build
password build
go
300 DATA s 12
CPU_ARCH X86
.
300 DATA s 22
CPU_MANUFACTURER Intel
.
300 DATA s 13
CPU_MODEL 586
.
300 DATA s 12
CPU_MHZ 1995
.
300 DATA s 16
CPU_LOAD1 97.333
.
300 DATA s 16
CPU_LOAD5 97.067
.
300 DATA s 17
CPU_LOAD15 97.356
.
300 DATA s 9
NUM_CPU 2
.
300 DATA s 17
MEM_PAGESIZE 4096
.
300 DATA s 14
MEM_TOTAL 2006
.
300 DATA s 12
MEM_FREE 605
.
300 DATA s 11
MEM_LOAD 70
.
300 DATA s 27
NET_FQDN server.ibm.com
.
300 DATA s 76
NET_IFACE Intel(R) 82566MM Gigabit Network Connection - AGN Filter Interface
.
300 DATA s 9
NET_IPV 4
.
300 DATA s 19
NET_IPV4 9.9.9.9
.
300 DATA s 13
NET_SPEED 100
.
300 DATA s 21
OS_SYSNAME Windows XP
.
300 DATA s 12
OS_VERSION 1
.
300 DATA s 12
OS_RELEASE 5
.
300 DATA s 14
OS_MACHINE x86
.
300 DATA s 18
WIN_SERVICE_PACK 2
.
250 RESULT 0
System parameter query complete.
.
260 EOR



[{"Product":{"code":"SSB2MV","label":"Rational Build Forge"},"Business Unit":{"code":"BU004","label":"Hybrid Cloud"},"Component":"Agent","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF022","label":"OS X"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"7.1;7.0.2;7.0.1;7.0","Edition":"Enterprise;Standard;Express"}]

Document Information

Modified date:
16 June 2018

UID

swg21370494