Getting started with the QuantumGate TestApp
This tutorial will guide you on how to start using the TestApp application that's included in the QuantumGate library. The TestApp is used during development of QuantumGate to (stress) test most of the features of QuantumGate. To be very clear, this application is not intended for stability and production use. It is designed to test and try to break things as much as possible whenever possible. As such you may come across situations where there's some unreliability and errors being reported. However, it does allow you to try out some of the capabilities of QuantumGate and get a general idea of what's possible.
The TestApp is included in the QuantumGate releases that include pre-built binaries and you can download those from the releases page on GitHub. Alternatively you can also download the source code and build all the binaries yourself using the instructions in the README file.
For the purposes of this guide we'll be using the TestApp on two computers and connect them to each other as shown in the image below.
We'll also assume that the mentioned computers are configured with the IP addresses shown below. You should use the actual IP addresses of the computers you're using to try this tutorial out. If you're using two computers on the Internet make sure to use their public IP addresses and not the ones on the internal network (behind a NAT).
| Peer / Computer | IP Address | TCP Port |
|---|---|---|
| A | 3.134.84.222 | 999 |
| B | 13.58.12.74 | 999 |
When you start the TestApp for the first time, you'll see the screen below. The first thing that you'll have to do is create a Peer UUID and associated asymmetric key pair that will be used by the instance of QuantumGate used by the TestApp. The Peer UUID and associated asymmetric key pair are used as the identity of the instance on the QuantumGate network. You can click on the 'New' button located next to the Peer UUID field to create a new identity.
After the new UUID is created, a message will be displayed indicating which UUID has been created and where the associated keys have been saved. Pay attention to the filenames of the keys; one starts with private_ and the other with public_. The private key should be kept private and never distributed, while the public key can be distributed to other peers along with the UUID when authentication is required (this is configurable; we'll come to that later below).
The 'Passphrase' field is used to create a Global Shared Secret for use with the instance of QuantumGate used by the TestApp. The Global Shared Secret provides enhanced security and authentication capabilities; you can read more about that in the documentation.
Follow the above procedure to create a Peer UUID in the TestApp on both computers. The Peer UUID should be unique for both computers (but this is not required).
Whenever you're using the TestApp, console messages from QuantumGate and the TestApp will be displayed in the small terminal window at the bottom of the 'Main' tab. This may not always be convenient to see, so there's an option in the TestApp for opening a separate terminal window. You can open a separate terminal window by going into the 'Console' menu at the top of the TestApp and choosing the 'Terminal Window' option. Monitoring the output in this window will make it easier to troubleshoot any problems.
Before we can successfully connect the two computers using the TestApp we'll first have to configure the QuantumGate instances to accept connections from each other's IP addresses. Specifically, on computer A we will need to allow computer B's IP address, and on computer B we will need to allow computer A's IP address. This can be done by going into the 'Local' menu in the TestApp and choosing the 'IPFilters' option.
A dialog will then appear allowing you to configure IP filters for the QuantumGate instance used by the TestApp. This dialog uses the same facilities that are built into the QuantumGate Access Manager; you can read more about the Access Manager in the documentation. The documentation also includes more details on how to configure IP filters.
You can add IP filters using the functionality in the 'Add IP filter' group at the bottom of the dialog. On computer A you can add computer B's IP address by filling in the fields as shown in the above image and then clicking on the 'Add Filter' button. The IP address will then appear in the above list of 'Configured IP filters'. After that you can click the 'OK' button to save the settings and exit the dialog. Use the same procedure to add computer A's IP address to the TestApp running on computer B.
For authentication the TestApp uses the same facilities that are built into the QuantumGate Access Manager; you can read more about the Access Manager in the documentation. You will find the API for the features mentioned below there. That API can be used when developing your own applications to provide similar functionality as the TestApp.
By default, authentication is required for peers connecting to a QuantumGate instance. This means that we will need to specifically add the identities of every peer we want to allow to connect to the QuantumGate instance. In the TestApp this can be done by going into the 'Local' menu and choosing the 'Peer Access Settings' option and then the 'Add/Remove Peers' option.
The below dialog will then appear.
Using the functionality in the 'Add Peer' group at the bottom of the dialog you can then add the identities of the peers that you want to allow. You'll need the Peer UUID of the peers as well as the public key file associated with that Peer UUID. On computer A you will need to add the Peer UUID and public key generated on computer B, and on computer B you will need to add the Peer UUID and public key generated on computer A.
Once you have filled in the required fields you can then click the 'Add' button and the peer information will be added to the 'Peers' list at the top of the dialog. You can then click the 'OK' button to save the settings.
If you don't want to use authentication and go through the above process of adding the peers to each instance, you can disable the authentication requirement. This can be done by going into the 'Local' menu and choosing the 'Peer Access Settings' option and then making sure that the 'Require Authentication' option is NOT checked.
Then you need to go into the 'Local' menu again and choose the 'Peer Access Settings' option and then the 'Add/Remove Peers' option. In the dialog that appears set the option for 'Default access for peers not in this list' to 'Allowed'. Then click the 'OK' button to save the settings.
You can now start the QuantumGate instance used by the TestApp by going into the 'Local' menu and choosing the 'Startup' option.
After the QuantumGate instance has successfully started it's possible to connect to other peers. On computer A we can try to connect to computer B by going into the 'Local' menu and then selecting the 'Connect' option. The below dialog then appears.
Specify the IP address, port and passphrase used by computer B and then click the 'OK' button. The TestApp will then try to connect to computer B. You can monitor the progress through the output in the console window. Once a connection has been successfully established it will appear in the 'Connected peers' list on the 'Main' tab in the TestApp.
If you continue to get security related error messages in the console when connecting, you may also need to check the reputations of the IP addresses involved on each instance and make sure that they have a good reputation. This can be done by going into the 'Local' menu and then choosing the 'Address Reputations' option. Then choose to reset the reputations if they are below acceptable levels. This can sometimes happen when trying to connect to instances multiple times that were initially not configured to accept connections from the IP addresses and peer identities you were using.
Also make sure that computer B is configured to allow incoming connections on the port you are using (999 in this example). Specifically check that the (Windows) firewall is configured to allow incoming connections to the TestApp on the port you are using.
You can get more information on connected peers by right clicking on a peer in the 'Connected peers' list on the 'Main' tab and then choosing the 'View Details' option from the pop-up menu. You can also disconnect individual peers from that menu.
Now that you've set up the basic settings in the TestApp and can connect to another peer, you can go on to try out the other features available on the other tabs. You may need to first load the required extenders on both computers A and B for the functionality on the other tabs to become available. For two peers to use functionality provided by a specific extender, they both need to have the same extender loaded and running. You can load extenders in the TestApp by going into the 'Extenders' menu at the top of the TestApp window.
Other tutorials will cover some of the features offered by the test extenders in the TestApp. Remember, once again, that these extenders are simple extenders written specifically to test some of the features of QuantumGate and illustrate certain use cases. They are not intended for production use.