I. Using SeMoA services and tools

(1) General information

• Use the shell command help to get information about the shell syntax.
• Use the shell command alias to display currently defined aliases.
• Most aliases and tool classes allow the parameter -help.
• The alias info prints further information about currently installed features.
• The alias semoaversion displays the current version of the SeMoA distribution.
• Some GUI screenshots of agents, tools, and applications are provided on the screenshot page.
• To change the bootstrapping behavior of the local SeMoA server, especially adjust the following shell scripts in semoa/etc: default master script (rc), global config variables (rc.global), global alias definition (rc.aliases), individual config files (demo?.conf).

(1) Status information about various SeMoA services

• The alias ship queries the Simple Host Information Protocol (SHIP) service to print information about installed services of the local or a remote SeMoA server.
• The alias vicinity queries the Vicinity service to display other SeMoA servers in the same local area network.
• The aliases http-info and https-info print information about the Web Server (HTTP/HTTPS).
• The aliases ws-info, ws-list, and wsm-status print information about the status of the Web Service Engine.

(2) Various SeMoA tools

• The alias ReloadPolicy reloads the role-based security policy for mobile agents, in case the corresponding file has been changed during runtime.
• The alias envision starts the graphical control interface Envision as alternative to the shell.
• The alias agentdirectory starts a GUI which can be used to download and install agent snapshots from a remote agent repository on the local machine.
• The alias tracer start a GUI which can be used to track locally started mobile agents. This too uses the Agent Tracking and Location Service (ATLAS).
• The alias sound replaces the standard agent migration gateways by new ones, which make a sound when an agent arrives on or leaves the local SeMoA server.
• The alias cat <file> displays the contents of the given file.
• The alias dir <path> display the contents of the given directory.
• The alias grep in the piped command <command> | grep [-c] [-i] [-v] <java-regex> is simulated the well-known grep command from UNIX/Linux.
• The alias ! [!|<nr>|-<count>|<prefix>|?<str> [<append>]]displays the content of the command history resp. re-executes a specific command from command history with the given argument appended.
• The alias findcert <dn> searches for a certificate with the given distinguished name.
• The alias classsource <classname> displays if resp. where the given class can be found in the JVM's class paths or extension directories.
• The alias classclosure <classname> displays the class closure of the given class corresponding to all classes in thr JVM's class path.
• The alias classfile <classname>|<classfile> parses the bytecode of the given class and displays some details.
• The alias Launch -class <agentclass> launches the given class, which must implement the interface java.lang.Runnable, as agent. For further information use the parameter -help. Another possibility to launch an agent is the Envision GUI (double-click on the service security/launcher).

(3) Crypto providers

• To realize various security features, SeMoA builds on cryptographic algorithms. The integrated JCE cleanroom implementation allows to install arbitrary Java crypto providers as e.g. the integrated FlexiProvider.
• The alias providers [-aliases] [-clear] [-add <provider-alias>|<provider-class>] lists all installed crypto providers, displays registered aliases for crypto providers, removes all installed providers, resp. adds the given providers.
• The alias providerinfo displays details about all installed crypto providers.
• The alias providersearch <search-keyword> searches for the given keyword in the property lists (ciphers, signatures, message digests, etc.) of all installed providers.

(4) Logging API

• SeMoA uses its own logging wrapper with a uniform API throughout the platform, which builds upon the logging framework from Sun or Apache.
• The default logging configuration is read from a file given by the Java system property de.fhg.igd.logging.config - usually the file etc/semoa.logging/
• The alias logconfig changes the current logging configuration during runtime. Type "logconfig -help for further information.
• The alias loglevel <class-prefix> ALL|TRACE|DEBUG|INFO|WARNING|ERROR|SEVERE|FATAL|OFF sets the given log level for all classes with the given prefix.
• The alias logall lets the logging framework log all messages on all log levels.

(5) Web Servlets Framework

• SeMoA provides a Web server implementing HTTP and HTTPS. Its Web servlet framework is compatible to Java's servlet specification.
• The aliases PublishServlet and RetractServlet publish resp. retract Web servlets implementing the interface javax.servlet.Servlet. Use the parameter -help for further information.
• The alias ListServlets lists all published Web servlets.
• Servlet examples can be found in the packages examples.servlets and de.fhg.igd.semoa.web.servlet.

(6) Web Service Engine (WSE)

• SeMoA transparently (for the developer and user) integrates Web services into the local service management of the Environment. Furthermore, we run a UDDI-Server which is implicitly used for Web service registrations and lookups.
• The aliases ws-deploy and ws-undeploy deploy resp. undeploy regular Java classes implementing at least one arbitrary Java interface as Web services. For further information use the parameter -help.
• The alias ws-client <wsdl-url> <environment-path> generates a Web service client for the given WSDL-URL and publishes this client within the local service environment under the given path.
• The alias uddi-lookup <webservice-name> searches for Web services which are registered at the UDDI-Registry with the given name. Wildcards ("-" and "*") are allowed.

II. Runnig example agents and applications

(1) JumpingAgent

• The jumping agent is a simple agent which may be used for the demonstration of agent migration.
• Launch at least two SeMoA severs with different identifications (e.g. demo1 and demo2).
• Start a jumping agent by typing jumpagent.
• At start-up and after every migration step the jumping agent searches for hosts in the LAN using the Vicinity service.
• All SeMoA servers that are found are presented in a drop-down menu. Note that the different servers can easily be distinguished by the last digit of the port number: demo1 ends with 1, demo2 ends with 2, etc.
• After choosing a server and clicking on the Jump button, the agent will terminate, migrate to the selected server and re-appear on that server.
• External hosts can be included using the command line option -hosts raw://semoa-host1:ship-port2 raw://semoa-host2:ship-port2 ....

(2) TimeAgent

• The time agent's task is to migrate to a time server and return to present the time on the remote host.
• Launch at least two SeMoA severs with different identifications (e.g. demo1 and demo2).
• Start the time agent by typing timeagent.
• An external host can be chosen as destination using the command line option -host raw://semoa-host:ship-port.

(3) ChatAgent

• The chat agent's task is to enable users to exchange text messages with each other.
• Launch at least two SeMoA severs with different identifications (e.g. demo1 and demo2).
• Start the time agent by typing chatagent.

(4) HSM agent

• The HSM agent's task is similar to that of the jumping agent, but this agent has been implemented using Hierarchical State Machines (HSM) as model to specify the agent's behavior.
• Launch at least two SeMoA severs with different identifications (e.g. demo1 and demo2).
• Start the time agent by typing hsmagent.
• In contrast to the jumping agent, you can see a bunch of logging messages on the SeMoA shell created by the HSM engine.

(5) Tic-Tac-Toe agent

• TicTacToe shows how mobile agents can be used for interactive, distributed multi-user games. Mobile agents allow moving complex states and algorithms from one host to another. In a simple example it is shown how a game board including state information and program logic is exchanged between two people who play a game of TicTacToe at two different SeMoA servers.
• Launch at least two SeMoA severs with different identifications (e.g. demo1 and demo2).
• Start TicTacToe by typing tictactoe.
• A detailed description of TicTacToe is omitted since the game is simple, well known and self explaining.
• Use command line option -help to list starting parameter.

(6) Postcard demo / Tourist agent

• This demonstration illustrates that agents can swiftly collect data from different, widely distributed servers and present the results to the user. Each SeMoA server runs a postcard service which offers an image to incoming agents that gives a nice impression of the server's location. A tourist agent may visit a number of hosts, collect postcards from different hosts and bring them back to the user. This gives a nice impression of the agent's journey.
• Launch at least two SeMoA severs with different identifications (e.g. demo1 and demo2).
• Start the Postcard demonstration by typing postcard.
• A window pops up that shows on the left hand side the destinations to visit. The possible destinations in the LAN are determined using the Vicinity service. Other location can simply be added by inserting them in the presented text field.
• A click on Launch tourist agent creates a tourist agent that starts its journey immediately.
• After a short time the agent returns with the collected postcards which are presented on the right hand side of the window.
• By selecting a postcard and clicking on View postcard the postcard is shown in full size with a stamp that indicates the time, the location of the server that was visited, the owner of the agent, and the name of the agent.
• The complete itinerary of the agent is shown by clicking on Journey diary.

(7) Car Control demo

• Automotive IT infrastructure, including in-car systems, garages, and dealerships, are highly distributed and have a very high need for security. Mobile code allows and easy and secure way of software updates, the performing of flexible diagnoses and the evaluation of sensor values.
• The car control demonstration is a simple demonstration that allows remote status checks and controls of a car's electronic system, e.g. window lift motor and sensors, door sensors, and locks. We assume that a SeMoA server runs on an embedded system within the car. Further we assume that the client part runs on a mobile device such as a PDA. Any communication is done by means of mobile agents who are authenticated and scanned for malicious code before execution.
• Launch at least two SeMoA severs with different identifications (e.g. demo1 and demo2).
• Start the car control server on one of the SeMoA servers by typing carserver. Start the car control client on another SeMoA server by typing carclient.
• The client GUI pops up. Select the register Server Setting and make sure that the URL of the Car Control server is selected.
• Query sensors: Switch back to register Car Status and click on Check Car Status. A number of agents are started, jump to the car control server, return to the client and display the current status of the car (the GUI still remains the same since the car's state has not changed yet).
• In order to open or close a car door, type use the alias cardoors -open|-close [frontleft|frontright|rearleft|rearright|trunk] at the car control server. Use the alias cardoors -status to display the status of the virtual car.
• After you opened or closed a door by hand you can re-query the car control server from the client GUI to get the actual car state.
• Activate actuators: Press one of the buttons for raising/lowering windows resp. locking/unlocking the car. The server prints out a status message when the action is performed and the GUI changes accordingly.

(8) Guestbook demo

• The guestbook demonstrator comprises a local service for guestbook entries, which can be accessed through a local Java application together with a GUI, through an agent, and via Web service
• Launch at least two SeMoA severs with different identifications (e.g. demo1 and demo2).
• The contents of the local guestbook, which is mapped to a file on the local file system, can directly be displayed through the alias guestbook
• The alias guestbook-add <guestbook-entry> adds a new entry to the guestbook, and the alias guestbook-agent starts an agent which travels to each SeMoA server found via the Vicinity service and subsequently creates a new guestbook on those servers.
• As alternative to the application accessing the guestbook service to print the contents of the guestbook, you can access the service via a published Web servlet with the path guestbook on the local Web server.

(9) EARTH demo

• EARTH allows the geographical tracking of mobile agent migration. Agent migrations across the earth are visualized on a globe. EARTH has a nice interactive GUI which helps to show and to explain agent migration, agent tracking using ATLAS, the distributed agent directory and implicit names. EARTH requires the installation of a native Java-3D library.
• Launch at least two SeMoA severs with different identifications (e.g. demo1 and demo2).
• Start EARTH by typing earth.
• A configuration window pops up. Choose Sphere Projector for an earth globe (or Cube Projector for a flat earth model) and click OK.
• The shown EARTH GUI is divided in three parts. On the right side you see a visualization of the earth, on the upper left a logical tree representation of the displayed objects and in the lower left information about the currently highlighted object.
• The earth globe can be rotated as follows: hold the left mouse button pressed for rotation, move the mouse left or right for rotation around the horizontal axis and up or down for rotation around the vertical axis.
• You can zoom in and out as follows: hold the middle mouse button pressed and move the mouse up or down for zooming in or zooming out. You can also zoom in or out using the slider bar at the right border of the window.
• Attach EARTH agent tracer GUI to SeMoA by choosing menu item AgentGlobalTracer from menu Tracer. A second window appears which shows all agents that are currently running within the local SeMoA server.
• There are two ways to track an agent: manually or automatically: Start an agent, e.g. the jumping agent, and manually add it by choosing the agent in the agent tracer GUI and clicking on the button Add to EARTH. A window pops up and you can set a nick name for the agent, e.g. Jumper. Add agent to EARTH automatically by selecting Add Agents automatically in menu Tracer". In this case all newly started agents will be added to EARTH automatically, with a generated name.
• The agent appears in the tree view in the folder Agents as a triangle and its nick name.
• After selecting the agent the earth globe is rotated to center on the agent's current position. The agent is represented as a little flag and the information panel shows the agent's current location.
• Send the agent to another host.
• A new flag appears at the agent's new position and an arch that visualizes the agent's "jump" from its last to the new position.
• Optionally, additional object can be shown, e.g. rivers, cities and provinces.
• To add provinces of Germany chose File -> Import -> ShapeFile and open the file Bundeslander.shp in folder countries/Germany. In the following window InputFilter you can configure the setting for these additional objects, e.g. visualization color. Set DistanceLOD to 7 and chose highDetail. Click OK and zoom closely into Germany. The German borders will appear when you zoom in closer than 7 percent.
• To add cities or rivers, follow the instructions above with file awriv3ml.shp or awscitie.shp.
• Note: A specific agent and all its traces can be made invisible by selecting the agent in the tree view and selecting Hide in the register properties of the information field. This may be used to get a clear view on the important agents and traces.

(10) Content Based Retrieval (CBR) demo

• Note: Because of an unsolved problem with respect to the order of installed crypto providers, Sun's SSL/TLS and our CODEC PKCS7 implementation currently cannot be used simultaneously within one SeMoA server on top of JDK 1.5.0. That's why, the SSL variable has to be set to disable in the file /etc/rc.global for this demo.
• Launch three SeMoA severs with different identifications (e.g. demo1, demo2, and demo3): Picture provider (vendor), customer (picture buyer) and attacker (malicious host).
• Start the CBR client on the first host by typing cbrclient, the CBR server on the second host by typing cbrserver, and the CBR attacker on the third host by typing cbrmalhost. Several GUIs will pop up on the different screens.
• Deactivate the SeMoA Decrypt Filter on all three hosts by pressing on the GUI.
• Select the URL of the second host (the ship port should be 55002) in the Net Vicinity panel and drag'n'drop it to the Selected sever(s) to index field of the CBR Index Tool on the CBR client host. Select the dropped URL and launch the incubator by pressing on the corresponding button. The incubator agent subsequently migrates to picture provider host, indexes the pictures and stays there to wait for retrieval queries of clients.
• Drag'n'drop the URL of the same server to Selected sever(s) to query field of the CBR Search Tool on the CBR client host. Press on the Browse button of the CBR Search Tool, change to directory lib/cbr/tinybase/images, and chose one of the JPG files to open. Press on the Launch a... button of the GUI. An agent migrates to the image provider searches for similar images and returns. The result can be inspected as thumbnails in the results tab of the CBR Search Tools.
• By clicking on one of thumbnails in the results tab, another agent is generated, which migrates to the image provider and actually "buys" the images, and returns with the image in high resolution. The bought image can then be inspected in the images tab of the CBR Search Tool. If Enable agents GUIs is selected on the options & log tab of the CBR Search Tool, the agent opens a GUI and the user has to confirm to Fetch image on the client host, and to Return image on the image provider host.
• First Attack: The customer selects a picture from thumbnails in results; The agent is intercepted by the attacker (this is simulated by selecting the malicious host - the ship port should be 55003 in the GUI of the FetchAgent and let the Jump to this server); The attacker overwrites the name of the requested picture by doing a drag'n'drop of the agent from the Local Agents panel to Drop agent to modify field of the Malicious Host GUI, entering another image name in the free text field of the Attack 1 tab, and launching the attack by pressing modify; When the agents continues its task (after the user has pressed on Fetch image), a Warning windows is opened, telling that the signature over the agent's static data is not valid anymore.
• Second Attack: The customer selects a picture from thumbnails in results; The agent first fetches the image and is then intercepted by the attacker on malicious host; The attacker can now launch the second attack. By pressing on the left image of Attack 2 tab, the attacker can steal, and by pressing on the right image, he can even replace the image. To protect the image data, the customer has to activate Secure retrieval for image encryption in the results tab of the CBR Search Tool on the client host, before generating a FetchAgent. In this case, the attacker has no access to the image.
• Third Attack: Continue with the last scenario as the FetchAgent has intercepted by the attacker, but the attacker is not able to access the plain image because of data encryption. In this case he can switch to the Attack3 tab of the Malicious Host GUI and launch the attack by pressing on cut/paste. Thereby, the attacker creates a new agent and copies the encrypted picture into this agent, which he can control. This agent is then sent to the image provider, who automatically decrypts all data he can access (including the image, he has encrypted previously). The agent then copies the plain image into another part its structure which is not automatically encrypted again, when leaving the host, returns to the attacker, and presents the stolen image. To prevent this type of attack, encrypted data has to be bound to original agent. To detect such cut&paste violations, the SeMoA Decrypt Filter have to be activated again.

(11) Web Servlet demo

• Reactivate SSL/TLS by setting the SSL variable in the file /etc/rc.global back to enable, if you have disabled SSL/TLS for the last demo.
• Launch at least one SeMoA sever (e.g. demo1).
• With the commands ls /network/httpd resp. ls /network/httpsd you can list all servlets currently registered for HTTP resp. HTTPS. With the alias ListServlets you get the same list with some more Servlet specific details.
• With the aliases "http-info" resp. "https-info" you can display on which ports the local Web server runs.
• Run the command PublishServlet -class examples.servlets.SnoopServlet -https -path snoop to publish another servlet only for HTTPS.
• Open the Web browser of your choice (e.g. Firefox) and enter the URL to the newly published servlet which consists of the protocol, the host on which SeMoA is running, the protocol-dependent Web server port and the path to the servlet (i.e. https://localhost:8881/test/snoop).
• Retract one of the registered servlets, e.g. by typing RetractServlet -https -path ship. Afterwards, this servlet should only be accessible via HTTP (i.e. http://localhost:8081/ship), not via HTTPS (i.e. https://localhost:8881/ship), anymore.
• Note: Even if the parameter -path suggests choosing a slash-separated path as servlet location, this servlet cannot be requested directly through this path via the Web server. Taking e.g. the path login/snoop for the above mentioned servlets, then a HTTPS request to https://localhost:8881/login/snoop is forwarded to a servlet with the path login together with the information about the full path. This circumstance can for example be exploited to create login servlets, which implicitly forward request to thereby associated servlets, only if the requesting user has been authenticated successfully by this login servlet.

(11) Web Service demo

• SeMoA's Web Service Engine (WSE) can be explicitly used via shell or via service interface. Furthermore, the engine can be configured through a configuration file (default: etc/webservice.conf) to transform specific locally published Java services automatically and transparent for the user and service developer into Web services, which are subsequently deployed over the local Web server and registered through a central UDDI registry.
• The automatic mode further implies that a Java service, which is not found in a specific region (subject to configuration) of the local service environment during a lookup request, is automatically requested through the UDDI registry. If found elsewhere, a corresponding Web service client stub is transparently create and returned as local service instance to the requestor.
• Launch at least two SeMoA severs (e.g. demo1 and demo2).
• Explicitly deploy the above mentioned guestbook service on the first SeMoA server by typing ws-deploy guestbook examples.guestbook.GuestbookServiceImpl * application.
• To verify the deployment process you can either type ws-list, or open a Web browser and enter the following URL: https://localhost:8881/webservice.
• Since we have used and extended the Apache AXIS implementation as basis for our Web service engine, you can use its functionality of simulating a Web service call via the Web browser: Click on wsdl link of the guestbook Web service. Now exchange the parameter ?wsdl in the Web browser's address field by ?method=getEntries and you will receive the corresponding SOAP response containing the encapsulated result of the method getEntries of the underlying guestbook service. Since this guestbook service has not been associated with a file on the local file system (see below), the service is not able to store any entries.
• Nevertheless, you can build a corresponding Web service client on the second server by typing ws-client https://semoa-host1:8881/webservice/services/guestbook?wsdl /test/guestbook, where semoa-host1 is the host of the first SeMoA server.
• Open envision on the second SeMoA server and double-click on test/guestbook. If you select the method getEntries in the ObjectPlugin and then press Invoke, the remote guestbook service on the first SeMoA host is triggered through the Web service protocol stack.
• Note: For the following part of the demonstration, the SeMoA servers must not run standalone. Thus, they must have connection to the internet and the variable STANDALONE has to set to disable in file /etc/rc.global.
• To check if the Web service engine actually runs in automatic mode type wsm-status.
• Implicitly deploy the guestbook service on the first SeMoA server by typing Publish -class examples.guestbook.GuestbookServiceImpl -key /webservice/test/guestbook \; -setFile ${GUESTBOOK_FILE}.
• Change over to the second SeMoA server and type uddi-lookup webservice/test/guestbook. At least one of the listed entries from the central UDDI registry should be the corresponding Web service binding point of the guestbook service you have started on the first SeMoA server.
• When you then type print /webservice/test/guestbook on the second platform, the WSDL description of the remote guestbook Web service stub is requested, a local Web service client stub is implicitly created, and then returned to the requestor. Since the reference to the client stub is not stored in this case, a repetition of this command has to re-create the client stub another time.
• Since classes have to be created and even compiled on the client side when used the Web service engine in automatic mode, it takes some seconds before the initially established Web service connection can be used.