Archived

This forum has been archived. Please start a new discussion on GitHub.

Documentation enhancement: Update to demo code

Hi,

I'd like to submit a proposal which will enhance the ICE documentation.
  • This particular problem will effect 100% of people that attempt to connect from a local PC to this ICE demo running on an internet server.
  • The solution does not seem to be mentioned anywhere in the official documentation (correct me if I'm wrong).
  • This problem delayed me by 8 hours, and required a fairly comprehensive forum post to get to the heart of it.
  • This particular problem seems to have affected a number of other people on the forum.
  • This proposal does not require any code changes, only documentation changes.
  • One possible reason reason why this might have slipped through Q&A is that most test scripts would be running purely on the local machine, its more difficult to actually deploy the demos to a remote internet server to test them (correct me if I'm wrong).
  • This proposal not only applies to the file "\Ice-3.4.1-demos\democs\Glacier2\config.glacier2", it also applies to all of the other languages (C++, Java, Python, Ruby, Objective-C, etc).
  • This documentation update applies to all demos which could be run on an internet server where a local PC calls a Glacier2 server on the internet.
  • I've thoroughly tested this solution on both my local machine, and an a client/server solution which calls to an Amazon EC2 web server. The IP address of 127.0.0.1 will simply not work at all, ever, if glacier2 is sitting on an internet server (it needs to bind to the IP address of the network card itself in order to receive connections).

Here is the current contents of "\Ice-3.4.1-demos\democs\Glacier2\config.glacier2":
#
# The client-visible endpoint of Glacier2. This should be an endpoint
# visible from the public Internet, and it should be secure.
# 
Glacier2.Client.Endpoints=tcp -p 4063 -h 127.0.0.1:ssl -p 4064 -h 127.0.0.1

#
# The server-visible endpoint of Glacier2. This endpoint is only
# required if callbacks are needed (leave empty otherwise). This
# should be an endpoint on an internal network (like 192.168.x.x), or
# on the loopback, so that the server is not directly accessible from
# the Internet.
#
Glacier2.Server.Endpoints=tcp -h 127.0.0.1

Here is the proposed revision to "\Ice-3.4.1-demos\democs\Glacier2\config.glacier2":
#
# If deploying entirely on the local test machine, this IP address is 127.0.0.1.
# If deploying on an internet web server, any IP address must match the 
# address of the network card obtained with ipconfig under Windows and 
# ifconfig under Linux.
Glacier2.Client.Endpoints=tcp -p 4063 -h 127.0.0.1:ssl -p 4064 -h 127.0.0.1

#
# The server-visible endpoint of Glacier2. This endpoint is only
# required if callbacks are needed (leave empty otherwise). This IP
# address should match the value in Glacier2.Client.Endpoints.
#
Glacier2.Server.Endpoints=tcp -h 127.0.0.1

In addition, this problem also seems to effect "Ice-3.4.1\Ice-3.4.1-demos\democs\IceGrid\icebox": the way Glacier2 is set up, it can never receive connections on port 4063 because the IP address is localhost, not the IP address of the internal network adapter. This means that even if you run everything locally, its impossible to connect to Glacier2 on port 4063. This slight omission becomes very clear when you deploy Glacier2 to an internet server, and attempt to connect to it from a local PC over the internet.

In conclusion, considering that one of the major use cases for ICE is writing internet based APIs, I believe that the existing demo set should be tested by deploying the server components to an internet server. I think you will pick up a lot of enhancements to the current demo set which will make it a lot easier for the future user base.

Finally, I'd like to thank the ICE team for the fantastic job they've done on the existing docs - the documentation really is almost 100% perfect. Its my hope that this minor update will save many hours of work for users in the future.

Comments

  • bernard
    bernard Jupiter, FL
    Hi Shane,

    Thank you for the suggestion. We'll try to improve the documentation and comments for this Glacier2 callback demo to make it clearer.

    Our existing comment for the Glacier2.Client.Endpoints is indeed not very clear in case the Glacier2 router is not directly connected to the Internet (a common situation). In this case, the IP address must correspond to the IP address of the interface that is mapped to the public IP. With Amazon EC2, the virtual machine has only one non-loopback interface, but this is not true for all servers.

    The second comment seems both clear and accurate. And your proposed update is not correct: Glacier2.Server.Endpoints is usually not the same as Glacier2.Client.Endpoints.
    In addition, this problem also seems to effect "Ice-3.4.1\Ice-3.4.1-demos\democs\IceGrid\icebox": the way Glacier2 is set up, it can never receive connections on port 4063 because the IP address is localhost, not the IP address of the internal network adapter. This means that even if you run everything locally, its impossible to connect to Glacier2 on port 4063. This slight omission becomes very clear when you deploy Glacier2 to an internet server, and attempt to connect to it from a local PC over the internet.

    When the Glacier2 router is configured to listen on localhost port 4063, you can connect to this router from localhost on port 4063. Naturally you need to update this configuration to connect to Glacier2 from another host.

    Best regards,
    Bernard
  • Thank you for taking the time to reply to my suggestion. I hope I can help in some way to enhance ICE, its a fantastic product.