JXTA Shell 1.0 Quick Start Guide

(Or, steps for fiddling with JXTA Shell, 04/25/01)

The JXTA Shell is a sample application that demonstrates some of the key concepts of
the  JXTA platform for the developer.  What you have downloaded is prototype code
that demonstrates some  of the features of the shell. This is not considered final code,
and you may experience bugs. In addition, as with most distributed systems, JXTA
benefits from a network effect of increasing numbers of peers on the network. Since
today's Project JXTA Network of peers is limited (only a few people have
had  access to the code and set themselves up in this environment), there
may be some delays in your initial process.

This guide gives a quick tour on how to install, configure and start using the Shell.

Install the JXTA Shell
Quick Shell Configuration
Troubleshooting
Quick Start
Other documents which may be of interest:
Shell Release Notes
Shell Build Process
Quick Shell Command Guide

1. Install the JXTA Shell

To install the JXTA Shell, download the current JXTA build for your computer platform
from the Project JXTA Installer Page The download page also includes detailed
instructions for installing the JXTA software on various Operating Systems and
Java configurations. Additional JXTA downloads can be found
on the Project JXTA Download Page.

2. Quick Shell Configuration Guide

The first time the JXTA Shell is run on your system, an auto-configuration tool  (JXTA Configurator)
is displayed to configure the JXTA platform for your network environment (behind a firewall or NAT,
rendezvous, routers, etc). If you are a newbie user, your best bet is to try executing the default setup
HTTP and TCP configured. This will give you the best chance to reach somebody else. The only
manual configuration you need is to select a JXTA router from the list of available routers. Project
JXTA tries to recognize your local network settings and apply them in the configuration. If you
the default settings aren't working as you'd expect, talk with your network administrator
about the following modifications:

If your system is behind a Firewall, you need to configure the HTTP transport. If your
web proxy was auto-detected, the tool will show the proxy found, if no proxy was
found, you need to select and enter a proxy configuration.

If you system is behind NAT, you need to configure the HTTP transport. You do not
need to select a web proxy. This is done in the default configuration.
We recommend that you always configure HTTP. By default, JXTA
is shipped with the HTTP transport configured (see JXTA configurator tool).
In order to configure HTTP you need to select:

This is a partial list of available JXTA rendezvous routers you can use. Please select the first peer in the list and enter it into the Router Selection box of the JXTA Configurator Tool. These routers are randomly ordered, so try the first one before trying others. 

In order to use the folowing list of routers you need unfortunatly to manually update the PlatformPeerGroup and PlatformConfig configuration files adding the new entries in the "jxta.service.resolver" service param list (Params Tag). You can list as as many rendezvous as you want. 

Additional routers may be available. Consult your application provider or the JXTA Project webpages for the names and addresses of more routers.

If the router you chose does not seem to work, ie. you cannot see rendezvous peers with the rdvstatus Shell command or peers with the peers Shell Command select another rendezvous from this. To reconfigure JXTA, just run the peerconfig Shell command and restart JXTA.

NOTE: If the Rendezvous server you use is not shown in bold above you must add the address of the rendezvous server to the "ResolverProxies" property of the jxtaConfig file. Once you have added the server you must reconfigure your JXTA enviroment by executing the "peerconfig" Shell command.

All configurations in the "Advanced Users" dialog box (JXTA rendezvous and router)
are optional and only apply to advanced users. We encourage users to read the
full Release Notes documentation about the platform configuration to configure
your peer as router or rendezvous peers for others.

When the Shell console appears, you can use the rdvstatus shell command to verify that your
configuration is correct. The command should display the rendezvous peers that were
discovered. The discovery may take some time depending on your network configuration
(30seconds-10 minutes probably).
 
 
JXTA>rdvstatus
======= Rendezvous status ======
This peer is connected to the following rendezvous:
Rendezvous id: jxta://59616261646162614A78746150325033C5CB4603DBA3456D83FCB6AA96C00AC6...zeros omitted...0301
This peer is not a rendezvous
JXTA>

In order to discover information beyond your initial subnet, it is necessary that you find
at least one rendezvous. To reconfigure the Shell just execute the peerconfig command
and exit the Shell via the exit command. Restart the Shell and the config tool will reappear.

3. Troubleshooting Problems

    The jxta.exe fails to run by throwing an exception.


    Try first to make sure to remove any configuration files jxtaConfig, PlatformConfig,
    PlatformPeerGroup, and the cm directory.
    If you still have problem, you may want check if you have IE 5.5 installed.
    We recommend that you use this version.
    If you have Java installed on your system you can also run directly:
    java -cp ../lib/jxta.jar;../lib/jxtashell.jar net.jxta.impl.peergroup.Boot
     

    You cannot  run two instances of the platform on the same peer.
    You need to change the TCP/IP transport port binding to enable two instances of the
    platform running on the same node.
     

    Cannot find peers via the 'peers' command
    No peers are running on your subnet.  You don't have a reachable
    rendezvous (check the rendezvous via the Shell command rdvstatus). The command
    should tell you that you are connected to a least one rendezvous. If it is not the case.
    Try to configure Jxta with a different JXTA router (see Quick Shell Configuration).
    Try to ping the IP address of the JXTA router to see if you can be located under
    your network configuration.

    If you are behind a firewall or NAT you need to configure the HTTP transport.
    If you are behind a firewall, you need to have enter a valid web proxy.
    At any time you can reconfigure JXTA by entering the Shell command 'peerconfig'
     

    HTTP was configured, but you want to modify the configuration
    Run peerconfig and restart JXTA.
     

    Platform fails to boot
    Remove all config files jxtaConfig, PlatformPeerGroup Platform
    Config and the cm directory

4. Quick Start
 

Quick Shell Scenario Guide:

In the examples below you will see monospace text enclosed in frames. This text is a transcript from the JXTA Shell. The text which is bold is text you should type to produce results similar to the sample results shown in these examples.

Find all the commands available in the Shell

For a quick look at what other commands are available, use the man command. It is the
primary help system for the JXTA Shell:
 

 
JXTA>man
displays man page about the Shell

The following is the list of commands available:

cat Display the content of an environment variable
chpgrp Change the default peer group
clear Clear the shell's screen
env Display all environment variables
exit Exit the Shell
exportfile Export a Shell variable into an external file
get Extract a message tag body from a pipe messsage
grep Search for matching patterns
groups Discover and list peer groups
help On-line Help about commands
importfile Import an external file into a Shell variable
join Join a new peer group
leave Leave a peer group
mkadv Make a new pipe or peer group advertisement
mkmsg Make a new pipe message
mkpgrp make a new peer group
mkpipe Make a new pipe
more Browse or page through a Shell object
peerconfig Peer configuration
peers Discover and list peers
put Put a new tag body into a pipe message
recv Receive a pipe message
search Search a shared advertisement in a peer group
send Send a pipe message
setenv Set the value of an environment variable
share Share an advertisement in a peer group
Shell Fork a new Shell
talk Instant messaging talk command
version Display version and build info
wc Count lines, words, and characters
whoami Display peer and peer group information
JXTA>
     
Get help on a specific command

To get help on a specific command, type man <command name>.

For example:
 

 
JXTA>man exit

NAME
 exit

SYNOPSIS
 exit - exit the Shell

DESCRIPTION
 'exit' command is used to exit the Shell

SEE ALSO

 Shell
Find information about you -- the current Peer

To find out who you are, use the whoami command. This will provide all the relevant information about
how the computer sees you, including the peer name, keywords search value associated with the peer,
the unique peer ID and the current address of the peer.The most important information for you will most
likely be on the first line. This is the name you entered during the configuration.

 
JXTA>whoami
<Peer>me</Peer>
<Keywords>NetPeerGroup by default</Keywords>
<PeerId>jxta://59616261646162614A78746150325033FEE11FF6BC4E476797E2A76FD28AE561...zeros omitted...301</PeerId>
<TransportAddress>tcp://129.144.38.126:6001/</TransportAddress>
<TransportAddress>http://JxtaHttpClient59616261646162614A787461503250331EB5F2F009AC4363ABCA85B51DD064A3...zeros omitted...301
An extended version of the whoami command which shows more information is available : whoami -l
 

Discover Other Peers

    The peers command is used to discover others peers. Used alone, the command will only show
    a list of peers local peers or peers previously found, and in your cache. The peers -r remote
    option is used to asynchronously discover new peers.

    The first time the command peers is run it will find only the local peers or pre-configured rendezvous peers.
    Each additional time it is run, the discovery will expand, and new peers may be shown :
     
     
     
    JXTA>peers -r
    peer discovery message sent

    ...after waiting a bit...
     
     
    JXTA>peers
    peer0: name = jxta-test
    peer1: name = diox.dioxine.com
    peer2: name = hs1
    peer3: name = diox.dioxine.com
    peer4: name = idvh
    peer5: name = skipstone
    peer6: name = Matt_UK
    peer7: name = luxor
    peer8: name = jgris
    peer9: name = toolbox
    peer10: name = bondolo
    peer11: name = sidus

    NOTES:
    Currently, depending on the network latency, peers discovery can be instantaneous or
    take from 2-4 minutes. Peer discovery on slow transports such HTTP, or when a remote
    connection involves lot of hops in case of firewalls or NAT configuration will take more time.
    This process continues to be optimized.
    At this release, JXTA is configured to list a random selection of peers found.If you are looking
    for a specific peer you know has registered, then you can use the peer -a -v options
    (see man pages ) to specify specific attributespeer discovery message sent
     

Discover Peer Groups

The groups command is used to discover peer groups.As with the peers command, the groups-r
remote option is used to asynchronously discover new peer groups. Without this option, the groups
command shows only the peer groups that have been previously found.

 
JXTA>groups -r
peer discovery message sent
    ...after waiting a bit...

     
     
     
    JXTA>groups
    group0: name = NetPeerGroup
    group1: name = toto
    group2: name = chacha
    group3: name = mynet
    group4: name = ooga
    group5: name = once
    group6: name = kaja
    group7: name = surfer
    group8: name = JXTA-webcast

    The groups command can be issued any number of times to list the new peer groups that may have
    been created and discovered. Depending on the network latency, groups discovery can be
    instantaneous or take from 2 to 4 minutes. Peer group discovery on slow transports such as
    HTTP, or when a remote connection involves lot of hops in case of firewalls or NAT configuration
    will take more time. We continually work on optimizing search times, and we anticipate
    future implementations to be more efficient.
     
     

Join a Peer Group

When you first run the shell you are, by default, joining a world peer group. This is usually not what you
want as most likely you will be looking to join a specific group and communicate with them. The join
command is used to join a peer group.Used alone, the join command lists any peer groups the peer
has already joined and which group your shell is currently active in. The first time you use the
command, no groups are shown.

 
JXTA>groups
group0: name = NetPeerGroup
group1: name = toto
group2: name = chacha
group3: name = mynet
group4: name = hiking
group5: name = once
group6: name = kaja
group7: name = surfer
group8: name = JXTA-webcast
    To join the group 'hiking'.

     
     
     
    JXTA>join -d group4

    If you are looking for a specific peer group you known has registered, then you can use the groups
    command -a -v options to specify search specific attributes.
    To find the group 'funstuff' and join it.
     
     
     
    JXTA>groups -r -a Name -v funstuff

    ...after waiting a bit...
     
     
     
    JXTA>groups
    group0: name = NetPeerGroup
    group1: name = toto
    group2: name = chacha
    ...
    group11: name = funstuff
    
    JXTA>join -d group11

    To join a peer group, one needs to have already discovered it. After using the groups -r command above,
    and then the groups command, you should have a list of groups to choose from. Used alone, the join
    command lists the groups you have already joined. To join a group, you must include the join -d argument,
    which means document. At this time, JXTA only recognizes the environment variables which are
    used to store the group advertisements, ie. "group" and some number.

    In this example, we will join the hello group.
     
     
     
    JXTA>join -d group12

    Enter the identity you want to use while a member of this peergroup
     
     
     
    1Identity: jxta_user1
    JXTA>

    Each peer group has a mechansim for identifying its members. When you join a group you must provide
    the group the identity you wish to use while you are a member of the group. In some groups many
    users may share the same identity, eg. "Anonymous", while in other groups, each user may have t
    heir own identity. The process for establishing your identity, such as passwords, certificates, etc.,
    is established by each peer group according to its definition.

    Once you have joined, you should be able to see the group you are in by using the join command by itself.
     
     
    JXTA>join
     Joined Group: hello (current)
    JXTA>

    When you have joined several groups, the join command will give you a list, and show which one is current.
     
     
    JXTA>join
     Unjoined Group : JXTA-webcast
     Unjoined Group : passwordtest
     Unjoined Group : improv-tech
     Joined Group: hello (current)
    JXTA>

    After joining a peer group, a peer can discover peers that are members of this peer group via the peers command.

    NOTE:

    Currently, JXTA is configured to list a random selection of groups found. If you are looking
    for a specific group you know has registered, then you can use the groups -a -v option
    command to specify specific attributes.
    JXTA>groups -r -aName -vbaseball*
    Use to search for a group which name contain 'baseball'. The '*' character is used as wilcard
    matching character (match any string containing the string 'baseball'). The search is XML based ie. <tag>value</tag>.
Talk to another peer in your group
     

    Once you are in a group, you can try talking with other peers within that group.The talk
    command implements a  simple messaging command where two users on two remote peers can
    exchange text messages. Messages are displayed on the Shell console.

    In order to use talk, the user needs to register, and set up a pipe for listening. This is done via the following steps:

    Register via talk -register <username> command.
    This command creates a Talk advertisement for that user. This has
    to be done only once; the first time the user registers with talk in a specific group.
     

    Login via talk -login <username> command.
    This command logs the user and starts a listener daemon. This command has to
    be issued every time the peer is restarted.
     

    Initiate talk with another user via the command talk -u <myusername> <destusername>
    This command will prompt the user to enter the message he/she wants to send.

    NOTE:

    In order to talk to someone else, one must have obtained the other user login name
    (this is not always the same as the user's peer name, and needs to be done done outside
    the scope of the talk command, by a separate email or by phone), and that user must be
    'listening,' i.e. the user must have also entered these steps.
    JXTA>talk -register jxta_user1
    ......
    User : jxta_user1 is now registered
    JXTA>talk -login jxta_user1
    ......
    User : jxta_user1 is now logged in
    JXTA>talk -u jxta_user1 jxta2
    talk is connected to user jxta2
    Type your message. To exit, type '.' at begining of line

    At thist point the user may enter as many lines as he/she wants. Each time "return" is pressed,
    that line is sent to the recipient. To end your message, enter a line beginning with a '.'

    To stop receiving any more talk messages. The user can stop the talklistener
    daemon by entering the command talk -logout <username>
     
     

Leave a peer group

The 'leave' command is used to leave a peer group.
 

 
JXTA>leave
JXTA>
     
Exit the shell
    Use the exit command.
 
JXTA>exit