XmlBlaster Logo

REQUIREMENT

admin.telnet

XmlBlaster Logo


Type NEW
Priority LOW
Status CLOSED
Topic You can administer XmlBlaster using a telnet client
Des
cription		 There is support to access xmlBlaster with telnet. You can for example query the free memory of the server JVM or shutdown xmlBlaster.

This is based on Remote Console of the WTTools project.

The plugin architecture of remotecons allowed us to add xmlBlaster specific functionality like internal state queries or setting of properties.

The default port to access xmlBlaster is 2702, configuring the port to 0 switches telnet access off (see below).

The query syntax is described in the admin.commands requirement.

How does the return value look like?

Responses of attributes have the key and the value, separated to lines. Messages are returned XML encoded.
The following table shows the return values of get invocations. The 'Impl' column marks the implemented features.

Command Return Description Impl
get ?numNodes 
/node/heron/?numNodes
5
The separator between the key and the value is '=' yes
get client/*/?uptime 
/node/heron/client/joe/?uptime=345600
/node/heron/client/jack/?uptime=19500
/node/heron/client/averell/?uptime=19500
The query matched three users, the lines are seperated by cr and lf (Wildcards are currently not supported) no
get ?clientList 
/node/heron/?clientList
joe,jack,averell,william
The clientList is one attribute, containing the list of known clients yes
get client/joe/?sessionList 
/node/heron/client/joe/?sessionList
1
joe is logged in once and has the public session id 1 yes
get client/joe/?subjectQueueNumMsgs 
/node/heron/client/joe/?subjectQueueNumMsgs
780
There are 780 messages in the subject queue of joe yes
get client/joe/1/?cbQueueNumMsgs 
/node/heron/client/joe/1/?cbQueueNumMsgs
5
There are 5 messages in the callback queue of the login session 1 of user joe yes
get client/joe/1/?numUpdate 
/node/heron/client/joe/1/?numUpdate
7537
The login session 1 of user joe has delivered 7537 messages to the callback client up to now yes
get ?serverTimestamp 
2005-03-21 11:31:35.044
The current time on the server yes
get topic/Hello/?topicXml 
<key oid='Hello' contentMime='text/xml'>
 <org.xmlBlaster><demo-1></demo-1></org.xmlBlaster>
</key>
 The XML markup of the topic yes
get topic/Hello/?numSubscribers 4 The number of subscribers for this topic yes
get topic/Hello/?numOfHistoryEntries 3 Number of queued back history entries for this topic yes
get topic/Hello/?subscribers /node/heron/client/joe/1, /node/heron/client/jack/-5, /node/heron/client/jack/-7 The list of subscribers for the topic 'Hello' yes
get topic/Hello/?peekHistoryMessages=2 

<MsgUnit index='0'>

 <key oid='Hello' contentMime='text/xml'>
  <org.xmlBlaster><demo-3></demo-3></org.xmlBlaster>
 </key>
  <content size='4'>Hi-3</content>

 <qos>
  <subscribable/>
  <sender>/node/heron/client/publish/1</sender>
  <expiration lifeTime='-1' forceDestroy='false'/>
  <rcvTimestamp nanos='1141465549697000000'/>
  <persistent/>
  <forceUpdate/>
 </qos>
</MsgUnit>
<MsgUnit index='1'>

 <key oid='Hello' contentMime='text/xml'>
  <org.xmlBlaster><demo-2></demo-2></org.xmlBlaster>
 </key>
  <content size='4'>Hi-2</content>

 <qos>
  <subscribable/>
  <sender>/node/heron/client/publish/1</sender>
  <expiration lifeTime='-1' forceDestroy='false'/>
  <rcvTimestamp nanos='1141465548969000000'/>
  <persistent/>
  <forceUpdate/>
 </qos>
</MsgUnit>
Access at most 2 messages from history queue yes
get topic/Hello/?historyQueueEntries= "maxEntries=3&consumable=true&waitingDelay=0" 

<MsgUnit index='0'>

 <key oid='Hello' contentMime='text/xml'>
  <org.xmlBlaster><demo-3></demo-3></org.xmlBlaster>
 </key>
  <content size='4'>Hi-3</content>

 <qos>
  <subscribable/>
  <sender>/node/heron/client/publish/1</sender>
  <rcvTimestamp nanos='1141465549697000000'/>
  <persistent/>
  <forceUpdate/>
 </qos>
</MsgUnit>
Query topic with a consuming tag set, it returns immediately even if not 3 messages are available. Setting waitingDelay=2000 would wait for 2 seconds and return before if 3 messages are available. yes
get _topic/?Hello 
<xmlBlaster>
  <key oid='Hello' contentMime='text/plain'/>
  <content>How are you</content>
  <qos><rcvTimestamp nanos='1291'/></qos>
</xmlBlaster>
The query returns exactly one message. deprecated: '_topic' uses the old implementation up to xmlBlaster 1.1.1, use peekHistoryMessages instead. yes
get _topic/?__sys__UserList 
<xmlBlaster>
  <key oid='__sys__UserList'>
  <content>
  joe
  jack
  averell
  </content>
  <qos>
   <state id='OK'/>
   <sender>admin</sender>
   <rcvTimestamp nanos='1291'/>
  </qos>
</xmlBlaster>
The query returns exactly one message deprecated: '_topic' uses the old implementation up to xmlBlaster 1.1.1, use peekHistoryMessages instead. yes
get org.xmlBlaster:nodeClass=node,node="heron"/ action=getFreeMemStr 
1.926 MBytes
All commands starting with 'org.xmlBlaster:' are treated as JMX commands and are forwarded to the JMX handler. The server be started with switched on JMX and in the above example should be named 'heron':
java -Dcom.sun.management.jmxremote org.xmlBlaster.Main -cluster.node.id heron 		yes

The next table shows the return values of set invocations:

Command Return Description
set client/joe/1/?sessionTimeout=2000000 /node/heron/client/subscribe/1/?sessionTimeout=2000000 Similar as the request
set client/publish/1/?addRemoteProperty=aKey&aValue /node/heron/client/publish/1/? addRemoteProperty=aKey&aValue Similar as the request
set client/publish/1/?addRemoteProperty=someKey errorCode=user.illegalArgument message=#1.1.1 wrong number of arguments: '1' but should be '2' An error as the method addRemotProperty(String,String) expects two arguments

Example
any 		Start xmlBlaster (port 2702 is default for telnet access). We configure the server to have a nice and short name heron: 
  java org.xmlBlaster.Main -cluster.node.id heron
and try a 
  telnet myHost 2702
Replace myHost with the IP where xmlBlaster runs.

Type help for a usage list.

Now lets login to play: 

  CMD>connect admin secret

  Successful login for user admin, session timeout is  [ 10 min 0 millis ]

Example to query the home directory of the user which started xmlBlaster and the current free memory in the server, the last example queries how many users are currently known in the server: 

  CMD>get sysprop/?user.home

  /node/heron/sysprop/?user.home=/home/xmlblast


  CMD>get ?freeMem

  /node/heron/?freeMem=942272


  CMD>get /node/heron/?numClients

  /node/heron/?numClients=0

Here is an example change the logging level of the authentication modules: 

  CMD> set logging/?org.xmlBlaster.engine=FINE

  /node/heron/logging/?org.xmlBlaster.engine=FINE

This example sets a variable with replacement (currently not very useful): 

  CMD> set sysprop/?myTmpPath=${user.home}${file.separator}backup

  /node/heron/sysprop/?myTmpPath=/home/xmlblast/backup

Now we kill the login session '1' of client 'joe'. To test it you should start a client with login name joe first. 

  CMD> get client/joe/1/?killSession

This would kill all login sessions of client 'joe'. 

  CMD> get client/joe/?killClient

Now lets query and change the run level: 

  CMD> get ?runlevel

  /node/heron/?runlevel=9

  CMD> set ?runlevel=3 

  /node/heron/?runlevel=3

Please read the admin.commands requirement for a description of the command syntax.

Example
any 
192.168.1.2 << help
remotecons.wttools.ConnectionServer$InternalCommands >> 
  echo           - switch 'echo' mode (for windows telnet is really needed)
  quit           - close connection to server
  who            - list all active connections
  close n        - close active connection number 'n'
  help [command] - display this message info

org.xmlBlaster.engine.admin.extern.TelnetGateway >> 
  XmlBlaster telnet administration
   connect [name] [passwd]  Login with you login name and password
   get [query]              Get property or xmlBlaster state
   set [query]              Set a property or change xmlBlaster setting
   time                     Display current time on server
   gc                       Run System.gc() command on remote system
   mem [total|free]         Display amount of memory on remote system
   exit                     Call System.exit(0) on remote system
  For query syntax see
  http://www.xmlblaster.org/xmlBlaster/doc/requirements/admin.telnet.html
  http://www.xmlblaster.org/xmlBlaster/doc/requirements/admin.commands.html
Configure
Property Default / Example Description Implemented
admin.remoteconsole.port 2702 Choose the port where xmlBlaster listens for telnet requests, 0 switches telnet access off. Port 2702 is a good port to try.
Example: 
java org.xmlBlaster.Main
         -cluster.node.id heron
         -admin.remoteconsole.port 2702
 yes
admin.remoteconsole.sessionTimeout 3600000 Auto logout after given milli seconds, defaults to one hour. yes

NOTE: Configuration parameters are specified on command line (-someValue 17) or in the xmlBlaster.properties file (someValue=17). See requirement "util.property" for details.
Columns named Impl tells you if the feature is implemented.
Columns named Hot tells you if the configuration is changeable in hot operation.

Todo

Most is done, testsuite is missing.

See http://wttools.sourceforge.net/remotecons/package.html
See API org.xmlBlaster.engine.admin.extern.TelnetGateway
See REQ admin
See REQ admin.commands
See REQ admin.jmx
See TEST

This page is generated from the requirement XML file xmlBlaster/doc/requirements/admin.telnet.xml

Back to overview