This document describes the Guru Server to help application developers write and maintain Guru Apps. Features and commands subject to change without notice. Please contact [email protected] to register your guru compatible Apps.
INTRODUCTION
Guru Services
Gurus provide the following services
Auto update of Guru Version
gurus check regularly for new guru versions and automatically update their code.
This process requires a guru close and restart but applications need not close.
This is via RiSoftwareUpdate objects. This operation can also update disk files.
Auto start of applications
gurus can automatically launch applications at start or any time thereafter.
Refer the Agent section
Object storage
Guru's main task is the storage and locating of objects. It also handles backup
distribution and access control
Guru Types
In addition to the storage and retrieval of objects Gurus also serve other roles.
update, and admin are some examples. RiGuruAddress objects are
the means to associate a physical Guru with one of these roles. RiGuruAddress
objects can be local (ri.sys.Owner = local guru ID) or not. Local addresses are used
to access the local roles. The type is stored in ri.sys.Type.
local/system client
Each computer has a local Guru which acts as a cache for all processes
on that machine. This is the 'local' guru.
system master
Each test system has one guru which is designated as the system guru. This
guru acts as a firewall to the outside network, provides DHCP, is the backup
update and admin server for all other gurus in the system.
clone
Clones are active replicas which share a common GuruID and public and
Private keys. Each also has its own GuruID and keys.
Each clone has an entry in the address book of type 'clone'.
backup
Backup gurus maintain a copy of a clients objects.
Each backup has an entry in the address book of type 'backup'.
The backup entry may be for a clone.
Backup gurus keep a record of clients
Defaults to use update guru
update
Each Guru can have a Guru from which it gets the latest updates for objects.
The address book entry of type 'update' and may be for a clone
Update gurus keep a record of clients
In a system defaults to system guru.
admin
Each Guru must have a Guru from which it gets admin info ( like permissions).
The address book of type 'admin' and may be a clone
Admin gurus keep a record of client
Defaults to use update guru
RI is ultimate admin
There is a separate Public Private key set for actual admin signing
RI
This is the root Guru at RI, this is a clone ID. The DNS is
guru.roos.com and port 50073 for RIRI
labguru.roos.com port 50099 for dev guru
guru2.roos.com and port 50073 for RIRI
guru2.roos.com and port 443 for RIRI via http
Guru Scopes
The searching by Gurus for objects is constrained by the scope selected. Scope is
set as a command attribute ( defined later ).
local
Each computer has a local Guru which acts as a cache for all processes
on that machine. This is the 'local' guru.
system
Each test system has one guru which is designated as the system guru. This
guru acts as the backup, update, and admin server for all other gurus in the system.
all
This is limited to all backup and update gurus only
RI
This is the root Guru at RI
Supported Environments and disk layout
Guru supports client applications in the following formats:
OS/2, Windows XP
D:\RiGuru
Object directories
GuruKey\
SystemID binary key for guru identity
D:\Riapps
GuruApps
application directories
Vast60RT\ VAST runtime support
DLL\ Smalltalk runtime support
jre14\ Java 4 runtime support
jre16\ Java 6 runtime support
Smalltalk OS/2
Java Windows, OS/2 , Linux (Java 1.4 and 1.6 only)
VAST Windows, OS/2 , Linux
Servers are Linux only. (SuSe 12.x, Ubuntu 12.04, 13.x)
Command line flags
To use: enter " -command <value>" after startApp.cmd
RiDebug - turn on debug message
RiLogSM - log system message
RiNoBackup - do not look for backup guru
RiNoUpdate - do not look for update guru
RiNoClone - do not look for clone guru
RiRootGuru - same as no backup no update
RiNoExpired - Does not delete expired object
RivBox - Support Cassini system software in VirtualBox, only for Linux and Windows host
RiUpdateGuru - IP address for the update guru, first try
RiBackupGuru - IP address for the backup guru, first try
RiMaxWait - Max wait time in milliseconds for the Guru communication default of 10 seconds
RiDeleteBadHash - clean up bad hash objects
RiRecoverBadAttrHash - will try to recover bad attribute hash
ex. set no update and no backup guru from OS/2 command window
[C:\] d:
[D:\] cd \RiApps\GuruServer
[D:\] RiApps\GuruServer] startApp -RiNoBackup -RiNoUpdate
ex. set guru communication time-out to 2 minutes from OS/2 command window
[C:\] d:
[D:\] cd \RiApps\GuruServer
[D:\] RiApps\GuruServer] startApp -RiMaxWait 120000
RiSystem Configuration Object Attributes
Guru stores its startup attributes in a guru object. These are reloaded whenever the user is changed (logon)
The object has the following query keys
ri.sys.ObjectClass=RiSystem
ri.sys.ObjectFormat=cff
ri.sys.Owner=GuruID
ri.sys.Name=Must be the GuruID
ri.sys.SystemID=Must be the GuruID
Supported attributes are:
AutoLaunch = number of second between checking for autolaunch, default is 601 seconds
ErrorLogLifeTime = 2592000 (in seconds, expired on 30 days)
GuruTimeUpdate = 86400 seconds (24 hrs)
NoClone = false do not check for clone guru
NoBackup = false do not check for backup guru, no object will backup
NoUpdate = false do not chekc for update guru
RootGuru = false, if true does not look for update, backup, or clone
UpdateGuru IP address for the update guru
BackupGuru IP address for the backup guru
MaxWait Max wait time in milliseconds for the Guru communication default of 10 seconds
NoExpired do not expire any object
vBox enable VirtualBox option,
SystemName = System name, default to title on the guru key or the guru id
SystemSN = system serial number, no default.
SystemUpdate = 7200 seconds (2 hrs), checking for Guru update
Update = 179 seconds, check for update guru
touch=on enables touch mode for the UI
simulation=on puts the system in simulation mode
Backup = 5 seconds between checks. for clone, 30 for other
displaySize= [email protected] size in inches width@height
epc3=on RIFL Master via IDE
remoteRifl=on Remote RIFL Master (RI8613A USB RIFL Master or RI8568D)
ritdbDir= path to data directory (DB Manager/Cassini Worksheet)) linux = /home/cassini/Cassini16-D/RiApps/data/ windows = C:\Users\Public\Cassini-D\RiApps\data
vBox-D= path to VM shared drive linux = /home/cassini/Cassini16-D windows=C:\Users\Public\Cassini-D\
NoGuruArchive=true does not create RiGuruArchive folder (local .GAB & .GOB clone of RiGuru), app level
CONNECTION TYPES
The current GURU implementation uses RiRi messaging over a stream ( TCPIP ) connection.
Guru servers use service discovery to find other guru's addresses and ports. For more information
refer to the Service Discovery document.
Further information can be found in:
Authentication/logon Document
RiRi messaging Document
Guru Discovery Document
Definitions
GURU TIME
Guru uses the concept of GuruTime to generate timestamps and system wide
unique IDs (TimeID). RiServers always have GMT time as operating system time.
GuruTime
GuruTime is the number of seconds ( integer ) since the start of Jan 1 1990 in UTC time.
TimeID
TimeID is an 8 byte structure where the first 6 bytes are the base36 GuruTime ( msByte first)
and the last 2 bytes are base36 sequence number. The sequence number is a means to extend
the IDs to more than one per second.
Base 36 is the integer values of 0 to 35 mapped to the acsii chars 0..9 and A..Z ( upper case only).
It is the responsibility of each Guru to guarantee that any issued TimeIDs are unique within itself.
If sequence exceeds ZZ before the second expires then the next second should be used.
On any machine the guru TimeIDs created must be monotonic.
GuruTime distribution
GuruTime is distributed in a top down fashion as part of the Guru-Guru socket connection.
GuruTime is always sent as 'GURUTIME=seconds' with seconds being an ASCII integer.
If a root is not available then the guru should attempt to obtain GMT time from a timeserver.
If a time server is not available then GuruTime is computed using the localTimeOffset stored
in the system address book object and the local clock time.
If GuruTime was not received from a root server then when a client connection sets the
attribute GuruTime= the guru will accept this as the correct time. This is to allow the use
of an agent to set the time.
LocalTime distribution
Local time ( wall clock time ) is computed via localTimeOffset in seconds and GuruTime.
This offset is added to GuruTime to get the wall clock time.
LocalTime is always sent as 'localTimeOffset=seconds' with seconds being an ASCII integer.
LocalTime is distributed in a top down fashion as part of the Guru-Guru socket connection.
If a parent server with localTImeOffset is not available then the local time is obtained from the
operating system.
OBJECT HIERARCHICAL KEY NAMES Defined
Hierarchical Key names used in guru have the following general form:
companyId.category.[subcategories].Keyname
or
local.companyId.category.[subcategories].Keyname
or
info.companyId.category.[subcategories].Keyname
The number of 'subcategories is 0..n where n is unlimited.
Local keys are maintained on the current Guru only and are not protected
They are intended for temporary use by agents
Local key/vals are never copied to other Gurus.
Local key/vals are not retained for history objects
Local keys are only created by KS. Object saves must not save local keys
Info keys are not searchable and may not be saved in the objects attributes
RI Defined Categories:
Pathname Description
--------------- -----------------------------------------------
ri.hw: Hardware
ri.test: Tester / Testplan / Exec related items
ri.app: Cross system applications
ri.dlog: Data logging keys
ri.sys: Guru System wide
local.ri.sys Guru local system ( not copied to other Gurus)
info. info only. Generated on demand so not stored
KEY/VALUE FORMATTING
Keynames: The only characters allowed in keynames are: a-z, A-Z, 0-9 and period '.'
Keynames are case insensitive when compared, however case is preserved in storage/retrieval
KeyVals must not include separators (16r1C,1D,1E,1F) or semicolons.
Within a keyVal a semicolon is used to separate multiple values
KeyVal allowed characters are:
upperCase lowerCase digit "-" "." "_" "~" "/" "?" "#" "[" "]"
"!" "$" "&" "'" "(" ")" "*" "+" "," ";" "="
KeyVal for file types allowed characters are:
upperCase lowerCase digit "-" "_"
BinaryString values are sent as Hex encoded strings with msByte first and msNibble first.
Date Syntax: (24 bytes fixed length) YYYY-MM-DD-HH:MM:SSS.sequence ie: 2000-04-01-14:07:02.0000
Date is always the local date and time.
Sequence is used to extend the resolution and should be '0000' if not used.
GuruID is the unique 8ch Id for a Guru
Boolean values are 'true' and 'false'
CIDs and RIDs
CID Creation Identifier, Uniquely identifies a file by concatenating a guru 8 byte ID with a TimeID.
A CID must be unique everywhere.
The CID is assigned by the guru doing the ObjectSave.
RID is a shorthand notation for ri.sys.RevisionOf. This is the CID of the root object for this tree.
It is the responsibility of the saving guru to ensure that CIDs assigned to objects with a common RID
are monotonically increasing in the TimeID portion. This is done by checking the local guru cache
for any other objects with that RID along with the CID provided with the save to find the latest TimeID.
Then using this latest TimeID as a floor for the new CID.
OID Object Identifier. Used where a key value needs to refer to a guru object. This can be the rid
or cid of the referenced object. When used the revisionOf is checked first and then the cid.
CURRENTLY ASSIGNED KEYS:
keys are divided into two groups Required keys and optional keys.
Some Object classes may make optional keys required for their instances
REQUIRED KEYS:
If not provided the guru doing the save ( create) must fill them in
Keyname: Comment:
--------------------------- -------------------------------------------------
ri.sys.Owner: The ID of the guru that owns (is responsible for) this item ( 8ch)
Defaults to the local guru ID
ri.sys.RevisionOf: Holds CID of root object which this is a rev of (Default to ri.sys.Cid).
READ ONLY REQUIRED KEYS:
The guru doing the save must fill them in
Keyname: Comment:
--------------------------- -------------------------------------------------
ri.sys.Cid Creation ID, a CID for this item when originally created ( new for each save)
ri.sys.Obsoleted Indicates that this object and all prior objects with this item's RID
are obsolete. Boolean, Defaults false. Only last revision is kept in search
tables
ri.sys.ObjHash SHA1 of object as HexString. If the Object has no body then the value
is 0
Locally Generated informational keys
Keyname: Comment:
--------------------------- -------------------------------------------------
info.ObjectSize size of the object in bytes.
info.ObjHash SHA1 of object as transferred in HexString. If no body then set to 0.
info.AttrHash SHA1 of attributes as transferred in HexString.
info.Signer GuruID for the Guru or CID of the RiCert which signed this object, validity check
info.ArrivalTime TimeID for when the object first appeared in this guru, defaults to file last write time
info.FilePath full path name to the object body file
info.AttrPath full path name to the object attribute file
info.Rcid owner and time stamp swapped from Cid
OPTIONAL KEYS:
Keyname: Comment:
--------------------------- -------------------------------------------------
ri.sys.Name Short name associated with this object
ri.sys.Title Descriptive string used to select objects from dialogs.
ri.sys.ObjFormat Indicates structure of file, eg: binary, cff, smalltalkV, java Class, ...
ri.sys.ObjFormatVer Indicates the format version
ri.sys.ObjClass Indicates the structure of the object defined by the file
ri.sys.ObjClassVer Indicates the structure version
ri.sys.PartOf Cid of some master object which this is a part of
ri.sys.Parent Rid of a parent object
ri.sys.Child Rid of a child object
ri.sys.Associate Cid of some object which this is associated with
ri.sys.Forked Cid of some object which this rid tree was forked from
ri.sys.Merged Cid of some object which was inserted into another
rid tree. Merged over the object getting its rid.
If an object has a merged and is saved again then merged
and forked keys are removed
ri.sys.AppPn Application part number
ri.sys.Version Sortable ( ascii sort) version identifier
ri.sys.SubVersion sub version identifier
ri.sys.SystemID Hardware serial number if this Guru runs a test system
ri.sys.Status Life cycle status, alpha,beta,released.obsolete
ri.sys.SortOrder Ascii sortable string for ordering
ri.sys.Type Used to subset within an ObjectClass or OpSys
ri.sys.SerialNumber Used for serial numbers
ri.sys.OpSys ALL, Linux, OS2, WIN
ri.sys.CreationDate Date/Time this item was originally created ( local time ) Time/date format
ri.sys.Manifest: When true indicates the cff includes a manifest def section. Default = false
ri.sys.TimeStamp Last 8 char of the CID for this item . Used for time sorting and not an actual key
File system like support
ri.sys.Name File name, VarType = file
ri.sys.FileDrive Example: "C:" includes the colon ' :'
ri.sys.FilePath Example: "/path1/path2" . "/" allowed
No trailing /. Must have a leading /
varType = file
ri.sys.FileExt: Example: "txt" no leading dot.
ri.sys.FileDate last write date and time (local)
info.ri.sys.Partial if = true the access did not return the entire object
If an partial object is sent to guru it is discarded.
This attribute is not saved to guru
HTTP keys
ri.sys.UriPath Any allowed URI path string per RFC 3986
Must have a leading '/' per HTML 5 sec 2.5.5
ri.sys.MimeType Any allowed media type per www.iana.org/assignments/media-types/
Security Support
ri.sys.ExpireOn TimeID this item expires
ri.sys.ValidOn TimeID this item becomes valid
ri.sys.Permission RID of an RiPermission
ri.sys.Password Sha1 of the password
ri.sys.User Holds RID RiUser which did the creation
ri.sys.Group Holds RID of an RiGroup
ri.sys.Role User role e.g. programmer, admin, operator etc
ri.sys.Vouchee Holds CID of the object vouched for by an RiVoucher.
ri.sys.Domain Admin authority for this object. RID
local.ri.sys.Encrypt GuruID for the Guru or the CID of an RiCert which can decrypt this object. Causes the object
to be encrypted during transfers
local.ri.sys.EncryptKey encoded key for decryption
Copy and Agent Support LGN is logical guru type
ri.sys.Copy GuruID of a destination., Remove object when done
Sends up the Admin path until it reaches the destination
local.ri.sys.Copy1 GuruID or LGN of a destination. Key is removed when done
If Transient = False this defaults to 'Backup', 'Parent' or 'Clone'
local.ri.sys.Copy2 GuruID or LGN of a destination. Key is removed when done
local.ri.sys.Copy3 GuruID or LGN of a destination. Key is removed when done
local.ri.sys.Copy4 GuruID or LGN of a destination. Key is removed when done
local.ri.sys.Copy5 GuruID or LGN of a destination. Key is removed when done
local.ri.sys.Copy6 GuruID or LGN of a destination. Key is removed when done
local.ri.sys.Copy7 GuruID or LGN of a destination. Key is removed when done
local.ri.sys.Copy8 GuruID or LGN of a destination. Key is removed when done
local.ri.sys.Transient Value is 'True' or 'False' implied False. What to do after all copies
complete. If True object is removed
local.ri.sys.LastUse Guru time seconds last accessed.
local.ri.sys.SaveScope local, system or all. Default is all.
local.ri.sys.Backup set to 'false' to prevent backup.
local.ri.sys.NextRun Guru time seconds at which to start. Set by agent when it completes a task.
local.ri.sys.Valid Boolean. Used to help with synchronization during copies which
have dependencies. Default is true
local.ri.sys.ExpireOn TimeID this item expires
local.ri.sys.Sandbox Name for the sandbox for this object. If present the object is not copied
to any other gurus
ri.sys.MaxInsts Maximum number of instances of this agent which can run. Default is infinite
ri.sys.MinInsts Minimum number of instances of this agent which can run. Default is 0.
If set to a non zero value then Guru will maintain that number active
Service Support
ri.sys.SvcId Identifier for this service instance
GURU RIRI Commands
1.0 Comments and Syntax
Separators are ^ (16r1C)for first (top) level and + (16r1D) for second level. ~ (16r1E) for third level
(16r1F) for fourth level
[] enclose RIRI submessages
Command is the first parameter and consists of a command string
optionally followed by a 16r1D and 1 or more keyName=value pairs
separated by 16r1D. These are referred to as command attributes.
Within a value 16r1E can be used to show multiple values
KeyList is +keyName+keyName...
KeyValList is +keyName=keyValue+keyName=keyValue...
ValList is ^+val11+val12...^+val21+val22.. Where ValXY is the value
for key X and Object Y. X is assigned by the order in the keyList
and Y by the sort criteria. If an Object does not have a
corresponding value then and empty string is used
Query is KeyValList+Sort where sort is hist:n, max:n, last, or all
all is all objects selected
last is the most recent as determined by guruTime
(lower part of cid)
last:n is up to n most recent objects
max:n is up to n objects in no order
hist:n is the n prior objects with the same ri.sys.RevisionOf
only applies to KeyValues command
KeyName='' is allowed in a query and means that a KeyName
must have a value, any value, '' is an zero length string
KeyName!=value is allowed in a query and means that a KeyName
must have a value, but not equal to value. Value can be value~value~value...
KeyName!=value~value~value... is allowed in a query and means that a KeyName
must have a value, but not equal to any of the values in the list.
KeyName=value~value~value... is allowed in a query and means
that a KeyName must have a value equal to one of the values
KeyName>=value is allowed in a query and means that a KeyName
must have a value, that is more than or equal to value
KeyName<=value is allowed in a query and means that a KeyName
must have a value, that is less than or equal to value
Searching, Obsoleted and Undo
Only the latest object in a revision tree is searchable. A revision tree
is where the value of ri.sys.RevisionOf is shared by all objects.
Obsolete objects have ri.sys.Obsoleted=true. The default sort criteria
is for ri.sys.Obsoleted=false. These objects become history and can be
accessed via the hist:n sort until the object is removed due to need for
storage space.
Undo works by allowing an user to select an older copy and then doing a
save to the same revisionTree making it the most recent. In addition SaveAs
is supported to allow recovery of specific objects
Usage of ExpireOn keys
The local.ri.sys.ExpireOn and ri.sys.ExpireOn keys act to remove an object
from visibility.
Currently the implementation is as follows;
If either local.ri.sys.ExpireOn or ri.sys.ExpireOn is exceeded then all objects
with a RevisionOf equal to the object expiring are removed (not obsoleted)
from the local guru's tables and file system.
Warnings and errors
Errors are returned by a special message format so there is no need to check
the reply contents as well. If an error is returned it is in key=val format using 1Dx
as the separator.
Supported keys are:
error = for error number
reason= for message string
Currently Defined errors ( error, reason)
100 Attribute not supported
101 Action not allowed
102 No Object Found when an CID was specified
103 Object Obsolete
104 Object exists
105 Too many objects selected
106 Access Denied
107 Request Timed out
108 Syntax error
109 Hash check failed
110 Communication failure, action aborted
Command Attributes
TTL=aInteger max number of guru hops. default =infinite
SRC=aList semicolon separated list of guruIds which have been passed
SCOPE=LOCAL limited to the local guru only
SCOPE=REMOTE ALL excluding the contents of the local cache
SCOPE=ALL default ex GR,KA,KV,OX goes to entire update chain plus backup
SCOPE=SYSTEM system wide
ENCRYPT=aGuruID guru which can decrypt this object
USER=16c 16c is revisionID of the user for determining permissions
USER=SYSTEM Used to indicate that system permissions are requested
default is current user's permissions
CHECKSIGNER=TRUE Forces the signer to be checked on each access
default is false
GURU Commands (client to server, and server to server)
-Attribute Query:
[^AQ^KeyList] ==> [KeyValList]
Queries Guru Attributes.
Private means available to local connections only and not CQ
[^AQ^all] returns all attributes
Server Supported Query Attributes
Name Guru Name from Guru key
GuruID Guru ID from Gury key
SystemID Guru ID for the system
userID revisionOf of current user
GuruTime Current Guru time as integer seconds
launchCid CID of the launching guru object
channel 2 char channel HEX string (ms nibble first)
localTImeOffset seconds to add to GMT time
localTime local time in date syntax
appPn part number for application (if set by client)
appVer version of application (if set by client)
systemSn user serial number in the RiSystem object
systemName user name in the RiSystem object
sessionId string identifier for the session
disableSystemMessages
controls system messages
GetHostByName_aName
returns the dotted IP address for the host with name
aName. Returns error 100 if no host of that name
Client Supported Query Attributes
appPn part number for application
appVer version of application
Error responses
ER,100,Attr not Supported (only if all requested keys are missing)
-Attribute Set:
[^AS^KeyValList] ==> [OK]
Sets Guru Attributes
Client to Server
buttonText string to put in button for launcher,
empty string terminates use of button
appPn the part number for the application
appVer the version of the application
smClientEnable true/false
enables system messages to the client. The client
is the end which initiates the connection
smMasterEnable
indicates that the master ( upstream connection)
will accept sm from the client
debugSystemMessages ( not yet )
sends all SM to this connection
sessionId string identifier for the session, only valid on open
loopback=n
Sets the number of milliseconds of inactivity (time-out period) for the connection
to be automatically closed by the server. IF loopback=0
precludes connection from automatically closed because of time out.
Server to client
GuruID Guru ID
SystemID Guru ID for the system
GuruITime Guru time in seconds
localTimeOffset seconds to be added to GMT to make local time
launchCid CID of the launching RiAutoStart
launchKeys KeyValues used in the SA command
userID revisionOf of current user
Top puts main window on top in display
channel 2 char channel hex string (ms nibble first)
logLevel a integer string indicating debug log detail, higher number
means more detail. '0' is no debug logging.
sessionId string identifier for the session
Error responses
ER,100,Attr not Supported. Only if an illegal name is specified
-Local Encode:
[^LE^String] ==> [Mod Power Bytes Hex String]
For local client to server only.
String to be encoded by the servers private key, returns the encoded string in Mod Power
Bytes Hex String (private).
Error responses
ER,106, Access Denied
-Local Decode:
[^LD^Mod Power Bytes Hex String ] ==> [String]
For local client to server only
Mod Power Bytes Hex String to be decoded by the servers private key, returns the
decoded string (private)
Error responses
ER,106, Access Denied
-Local Key Delete:
[^KD^Query^KeyList] ==> [OK]
For any items matching the query
Deletes the specified keys from them (if they exist)
Error responses
ER,101, Cannot Change non local keys
-Local Key Set:
[^KS^Query^KeyValList] ==> [OK]
For each item that matches the query
Set its keys as per the given "key=val" list
Error responses
ER,101, Cannot Change non local keys
-Log Message:
[^LM^KeyValList] ==> [OK]
posts a message to a logging/viewing function
supported keys:
message text message to show
severity Fatal System, Fatal application Error, Messages
level Applies to messages only, All, major
source application identifier string
Error responses
none
-Log Messages Query:
[^LQ^Query^KeyList] ==> [ValList]
Given the set of items that match the query criteria.
Returns a Val list covering each matching message.
Queried items are removed from list
-Key Names:
[^KQ^Query] ==> [KeyList]
Returns list of used key names by items that match the query.
Note: If multiple items match, returns the union
of all used keys. Used by selectors to get allowed names
Returns the union of the scoped gurus. Duplicates are removed
Error responses
ER,102, No Object Found
-Key Range
[^KR^Query^KeyList] ==> [ValList]
Given the set of items that match the query criteria. and
returns 0 or more items each of which is a list of unique values
for that key (ie: per key in keylist order, used for creating
select lists for menus etc.)
Returns the union of the scoped gurus. Duplicates are removed
Error responses
ER,102, No Object Found
-Key Values:
[^KV^Query^KeyList] ==> [ValList]
Given the set of items that match the query criteria.
Returns a parameter list for each matching object.
(ie: per object, used for indexing, getting values of objects...).
KeyList must include ri.sys.Cid, ri.sys.Rid and ri.sys.Permission
if not they are added
Returns the union of the scoped gurus.
Duplicate Cids are removed
Expired and Obsolete objects removed
Only latest in Rid tree provided
Permissions applied
Error responses
ER,102, No Object Found
-Object Key Values:
[^KA^Query] ==> [KeyValList]
Retrieves all keys (local and global) for item matching the query
If more than one item matches then returns error
It is recommended that The Query specifies ri.sys.Cid only
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied
-Object Retrieve:
[^OR^Query] ==> [objectBytes]
Retrieves data bytes for item matching the query
If more than one item matches then returns error and no action occurs
If CID is specified and no object available then error is sent
If newer version found update the local Guru
If the object is encrypted and this guru has the decryption key
and the Client has permission the object is decrypted before transfer
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied for CID
-Object All:
[^OA^Query] ==> [KeyValList][objectBytes]
Retrieves attributes and data bytes for item matching the query
KeyValList includes local attributes
If more than one item matches then returns error and no action occurs
If CID is specified and no object available then error is sent
If newer version found update the local Guru
If the object is encrypted and this guru has the decryption key
and the Client has permission the object is decrypted before transfer
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied
-Object Partial:
[^OP^Query] ==> [KeyValList][objectBytes]
Retrieves attributes and 20K max data bytes for item matching the query
If more than one item matches then returns error and no action occurs
If CID is specified and no object available then error is sent
If newer version found update the local Guru
If the object is encrypted and this guru has the decryption key
and the Client has permission the object is decrypted before transfer
The attributes
info.ri.sys.Partial is set to true
info.ri.sys.ObjectSize is set to the size
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied
-Object Save:
[^OS^KeyValList][GuruFile] ==> [KeyValList]
Creates a new item with attributes as specified in the "key=val" list
and with the given data. The returned KeyValList has all of the keys
in it.
If local attributes are specified they are saved
Error responses
ER,102, No Object Found for CID
ER,106, Access Denied
-Object Delete:
[^OD^Query] ==> [OK]
Deletes (obsoletes) this object from the guru file system.
Does this by saving a copy of the object with ri.sys.Obsolete=true
Still available via history query
Query must be ri.sys.Cid= only
Error responses
ER,101, Action Denied
ER,102, No Object Found for CID
ER,106, Access Denied
GURU to GURU Commands
-Object Newer:
[^ON^aCid+aRid] ==> [attrBytes][objectBytes]
Retrieves newer item with attributes as specified by aCid and aRid
or returns no Object found
If the object is encrypted and this guru has the decryption key
and the Client has permission the object is decrypted before transfer
Error responses
ER,102, No Object Found
-Guru Save:
[^GS^attrBytes][objectBytes] ==> [OK]
Copies Exact bytes to another Guru
Local attributes are not included
Error responses
ER,104, Object Exists
ER,106, Access Denied
-Guru Retrieve:
[^GR^Query] ==> [attrBytes][objectBytes]
Retrieves new item with attributes as specified in the "key=val" list
Local attributes are not included.
If the object is encrypted and this guru has the decryption key
and the Client has permission the object is decrypted before transfer
If cmd attribute Encrypt=Guruid is set then the entire transfer is encrypted
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied
-Guru Keys All:
[^GA^+aCid] ==> [attrBytes]
Retrieves attributes bytes for an item specified by aCid
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied
-Guru Clone:
[^GC^attrBytes][objectBytes] ==> [OK]
Copies exact bytes to a clone Guru.
Local attributes are not included
Error responses
ER,104, Object Exists
Special commands
-Object Remove:
[^OX^Query] ==> [OK]
Removes this object and all of its history from this guru file system.
Does not remove the object from all gurus. Use delete for that.
Query must be ri.sys.Cid= only
Error responses
ER,101, Action Denied
ER,102, No Object Found for CID
ER,106, Access Denied
-Targeted Remove:
[^TR^Query] ==> [OK]
Remove each item that matches the query
Used for clean up by removing a batch of selected objects but not other
objects in the chains.
Error responses ( does what it can and if error )
ER,101, Action Denied
ER,102, No Object Found
ER,106, Access Denied
-Start Application:
[^SA^Query^KeyValList] ==> [OK]
Retrieves item matching the query. The result of the query must be of
ObjectClass RiApplication. or RiShortcut
If more than one item matches then returns error and no action occurs
If newer version found update the local Guru and execute the request
Start the application.
If an RiApplication then launch it
If an RiShortcut then process the shortcut
If a RiShortcut was used pass the cid of the shortcut as the launchCid
If KeyValList is not empty pass it to the application as additions to Guru
Attributes
Additional CmdAttributes
closeWait=seconds Causes the sending application to be sent
the Exit Application command. Then wait an
integer number of seconds before launching
the new application
Error responses
ER,102, No Object Found for CID
ER,105, Too many Objects Found
ER,106, Access Denied
-Exit Application:
[^XX]
Forces the application to close, only sent to local clients
Error responses
ER,101,Cannot close
-Connection Query:
[^CQ^all] ==> [^KeyValList^KeyValList....]
Returns a parameter of KeyValList for each connection this client has.
These KeyValLists are the public attributes of the connection.
Error responses
ER,102, No Connections
ER,106, Access Denied
-User Changed: ( local guru to applications only )
[^UC^KeyValList] ==> [KeyValList]
When sent by guru notifies an application that the system user has changed.
When sent to guru sets the user for the application instance
UC s sent only when the user actually changes, it is not sent when an application
of Guru restarts. Use the attributes at these times to determine the user
Supported KeyNames
UserID revisionOf of the current user ( 16 char )
Error responses
-System Message:
[^SM+cmdAttr^channel^message...][opt payload]
Sends a message based on the command attributes.
channel is a string used to determine the parsing for this message.
can be zero or more messages
The payload is treated as binary
System messages are asynchronous inter process messages which use the existing Guru to
Guru channels.
When a Guru receives a SM on one of its local connections it
examines the command attributes and routes the message based on them.
Error responses
There are no immediate errors or replies
Refer to the System Message Specification for more information
ERROR LOGGING
Major errors are persistent and are saved as Guru Objects of Class RiErrorLog.
SANDBOX (not yet implemented)
There is often a need to load objects temporally into a guru for testing and then
removing them in order to prevent their use by other users. At the same time these
objects must be limited in propagation to only the guru targeted. This function
is referred to as sandboxing.
A sandboxed object is identified by having a key local.ri.sys.Sandbox=aName. Where
aName is any descriptive string.
Objects are placed into a sandbox by adding the cmdAttribute SANDBOX=aName
to any object save or copy request.
Objects which are in a sandbox will not be copied to any other connected gurus.
Special Cases
If an object which already exists in the target guru is directed to a sandbox the
object is not placed into the sandbox. This is to prevent the user losing objects
which they already have via a sandbox operation.
APPLICATION/AGENT LAUNCHING
LOCAL LAUNCH
Launch from the local control panel by title only from the 'apps' button
SHORTCUT
A shortcut is a guru object which has information to allow an app to modify
itself during launch. This allows customization of the application run process.
Shortcuts can be of any object class but only those of object class RiShortCut
will be shown as a selection.
There can be a chain of shortcuts. Each trailing shortcut refers to either an
AppPn and version or to the rid of another shortcut (AppDef). The first (root )
must always refer to an AppPn.
RiShortCuts have the following GuruAttributes
ri.sys.ObjectClass = RiShortCut
ri.sys.ObjectFormat = cff
ri.sys.Title used to select
ri.sys.AppPn the application to launch
ri.sys.Version the application version to launch
ri.sys.AppDef the rid of a prior shortcut to load, Only one of AppPn or AppDef
is allowed
ri.sys.OpSys The operating system which it support, default is all
ri.sys.SystemID GuruID of which system that can launch this short cut, default is all
ri.sys.Status alpha, beta, released, obsolete
The displayed list will be determined as:
if programmer = true in RiUser
all shortcuts
if programmer = false
only shortcuts where:
status= released
and if ri.sys.SystemID has a value then it needs to
match the GuruID of the this guru
When a shortcut is selected Guru will search the chain until if finds and AppPn and Version.
This Application is then launched and passed the cid of the selected shortcut as the
launchCid.
If another shortcut is selected with the same application and version then the launchCid is sent as
an attribute to the running application.
REMOTE LAUNCH
Launch from a Start Application Command
AUTOSTART
Operation
Guru starts up and waits for running agents to connect ( 20 seconds ). After the
first search the guru searches every 2 minutes thereafter.
1. Search for objects with the following key values
ri.sys.ObjClass=RiAutoStart
ri.sys.Owner=this guru ID
ri.sys.ObjFormat=cff
2. Discard any objects where ri.sys.ValidOn is not yet happened or any objects
where ri.sys.ExpireOn is past. If the autostart which is expired is still running it
is closed and the object is obsoleted.
3 Only during the first search after a guru start these objects whose Type=startup
and which are not running are launched
4 All these objects whose Type=normal, are which are not running and NextRun is
not present, nil or is a prior time are launched
Auto starts uses the following keys:
ri.sys.Owner: Guru ID for system on which this is valid
ri.sys.ObjClass=RiAutoStart:
ri.sys.ObjFormat=cff
local.ri.sys.NextRun: Guru time seconds integer at which to start
ri.sys.ExpireOn: Guru time is seconds integer at which to obsolete
default is never expire
ri.sys.ValidOn: TimeID this item becomes valid (Guru Time seconds as integer)
default is always valid
ri.sys.Type: normal, startup. defaults to normal
ri.sys.Status: alpha,beta,released.obsolete. Default is released
only RuAutoStarts with status = released are auto started
The guru object is a cff file with the following structure:
:INFO key value pairs used in launching and configuration
application= ' guru key value pairs '
:xxxx application specific paragraphs
Access Control to Guru Objects (filters)
Refer to RiUsers document
GURU IDENTITY and Security
Dongles and DongleFiles
USB RAM dongles or encrypted key files are used to store RiKeys . They are
accessed during guru start up to provide all of the PrivateKeys which a Guru is entitled to.
Refer to the Guru dongles/keys/certs specification
Security Parameters For Objects
Guru objects are protected by three features; hashing which protects transfer integrity, signing which
verifies the source and accuracy of the object and encryption which hides the object itself.
These features are added by appending a security parameter after the normal guru file attributes
parameter using a 16r1C separator. In all cases the security parameter to use is the last security
parameter in the attributes file. This allows encrypting the attributes multiple times each with its own
secruity parameter. As the decryption is done its security parameter is dropped.
In Guru to Guru messages the guru file attributes are referred to as attrBytes. They have no leading or
trailing separators. The attribute file should match unless some encryption is done on receipt.
The format of each is in key=value pairs just like the guru file attributes.
Allowed keys and values are
ObjHash=hex SHA1 of the object portion as transferred
AttrHash= hex SHA1 of the parameters up to (not including) the 16r1C separator of prior parameter
SIGNER=guruID of the guru who signed the object, local.ri.sys.Signer.
SIGN=hex string for the signature
ID=guruID for the guru which this is encrypted for, local.ri.sys.Encrypt
TYPE=blowfish type of encryption used, default = blowfish
KEY=encryption key encrypted by the public key of the ID and converted to hex local.ri.sys.EncryptKey
PRIVATEATTR= hex encoded byte array of private key=value pairs encrypted the same as the body.
The SIGN is concatenation of the attrHash+ObjHash encrypted by the private key of the signer and converted to hex.
ObjHash,AttrHash, SIGN and SIGNER are required. Guru keys are at least 512 bits to allow encoding 320 bits.
USAGE
Signing and encryption is handled by the Guru handling the ObjectSave command, if it cannot do the
requested action it returns an error. Keys for signing can be the guru key, keys on an attached dongle
or inside the RiUser object.
Only the objectBytes are encrypted. The attributes are not. The signing is done before the
encryption.
As each guru receives an object is must check the object and attribute hashes. If they do not compare
the transfer is to be rejected and an error is returned.
If the receiving Guru can decrypt the object it does and saves it locally unencrypted.
If the Cert for the signer is not available the object is to be accepted. If the cert is available the
signature is verified and the object rejected if it fails.
Disk Space Reclaimation
Whenever an ri.sys.ExpireOn is of a past time the object is obsoleted.
The current GURU implementation does not reclaim space except by explicit action. If disk space is
needed the following rules will be used to reclaim space.
Objects which are expired.
Object history for objects not owned by this guru.
Obsolete objects and history not owned by this guru.
Object history limited to 10 versions or 6 months whichever is greater if owned by this guru