QuickBooks Enterprise
Does the QuickBooks Connector need to be running for Ground2Cloud to work with QuickBooks?
Yes. If the QuickBooks Connector is not running, then there's nothing listing for REST requests made to QuickBooks; from the Ground2Cloud perspective, it's as if QuickBooks itself isn't running.
Does QuickBooks have to be running?
Yes. In general, a service has to be running for Ground2Cloud to connect to it. See "What happens if my service is halted?" below.
Does the QuickBooks Connector support multi-user mode?
Yes. When you first start up and authorize the QuickBooks Connector, QuickBooks must be running in either (1) single-user mode, or (2) multi-user mode logged in as Admin. After that point, as long as QuickBooks is running, the Connector will be able to read and write its data.
Using Ground2Cloud
How do I change what environment I'm connected to?
Maybe you want to switch to our staging environment to debug a problem. Maybe you're a Ground2Cloud developer, and you want to connect to a local server for testing. In any case, if you want to connect to a different Ground2Cloud server, follow these steps:
- Unregister the current connection on the Manage tab.
- Change the "host" (and possibly "user") in the Config tab to the server. If you don't know the host or IP of the server you want to connect to, contact Cloud Elements support.
- Register in the Manage tab.
As with every time you re-register, you may receive a new key, tunnel port and/or registration ID. When switching to a new Ground2Cloud server, you will almost certainly get a new endpoint.
When authenticating an element instance what endpoint / hostname do I use?
When creating an element instance (or when using "raw" Ground2Cloud), you need an API endpoint to access your service. If your Ground2Cloud is registered, then this endpoint is shown in the Manage tab in the Ground2Cloud GUI. (This value is also written to a file named C:\Ground2Cloud\endpoint, in case you want to access it programmatically.)
If you're using an element that doesn't use a HTTP-based API (such as the MySql and PostgreSQL elements), you need to instead use the tunnel port number. This port number is also shown in the Ground2Cloud GUI. You can only connect to this port using the Cloud Elements Platform: direct connections to the tunnel port from outside the Cloud Elements environment are disallowed.
Security and Firewalls
What security features are in G2C?
G2C is a port forwarding mechanism that uses an SSH reverse tunnel to forward connections to a private hosted service, and provides a simple HTTP/HTTPS proxy to make forwarding those requests easier. In addition to whatever application-level authorization / authentication mechanism the service itself provides, G2C adds the following security features:
- Secure generation and storage of individual private keys on the client.
- TLS 1.2 protection of the data stream through the tunnel.
- Uses elliptic curve25519 cipher, allowing for perfect forward secrecy.
- This is done in addition to whatever encryption (if any) is supported by the service.
- Server validation via certificate authentication.
- Client validation via certificate authentication
- Standard HTTPS on the proxy with a certificate signed by a trusted public authority.
- Server multi-tenant enforcement to prevent cross-client contamination.
- The client installer, uninstaller, and updater(s) are signed by a trusted public authority.
How are my keys created / used?
During Ground2Cloud registration, the client on your machine generates a 2048-bit RSA asymmetric key pair, and sends the public half of that pair to the server; the private half is kept on your machine, and is never shared. Once the server verifies the integrity of the key, it responds with a unique registration ID. From that point forward, all service communication is identified by that ID, and protected via the TLS 2.0 protocol using those keys.
Is key rotation supported?
Currently, you can rotate your key manually by unregistering, and then re-registering the client in the Manage tab of the GUI. When you do this, there is a small window of time during which Ground2Cloud is not active. Also, there is a slight chance that when you re-register, you will not be granted the same registration ID, endpoint, and/or tunnel port.
Do I need to change my firewall settings?
Ground2Cloud is not a server in the traditional sense: it does not receive incoming socket connections, and thus doesn't require any firewall configuration changes, either on its host machine, or on its network edges. The local service that it connects to also requires no firewall settings, because Ground2Cloud is designed to connect to it from inside its firewall.
The only exception is if your router or firewall has restrictive egress (outgoing) filtering enabled. Most Windows Home and Windows Pro configurations do not have to worry about this: see the next question for details.
What egress filtering should I know about?
Most personal computer configurations don't have to worry about the kind of egress filtering mentioned here. However, if your client machine or network is configured to restrict outgoing connections, you should read this.
The Ground2Cloud client works by making long-lived outgoing connections to a server, through which traffic can be funneled back into a specified local service. If your firewall, router or similar edge device has egress (outgoing) filtering enabled, you may need to adjust your rules to allow the following:
- Allow TCP connections from the client to port 22 (the standard
sshport) of the server. - Allow TCP connections from the client to port 3014 (the Ground2Cloud backchannel port) of the server.
Additionally, the client software makes periodic "full loop" checks to the server's front door, to verify and keep alive the entire Ground2Cloud pipeline. The host and port used for these belong to the endpoint shown in the GUI Manage tab (if the port is not shown, it is port 80 for http connections, and port 443 for https connections). You may need to allow this outgoing connection as well, or accept the consequences of the loop check failing.
All connections established by Cloud Elements are standard TCP or TLS using configurable port numbers; using a proxy here should be possible. Contact Cloud Elements if you want the Ground2Cloud client to operate through a proxy, if you have other advanced network configuration needs, or if you have further questions about Ground2Cloud network usage.
Stability and Recovery
What happens if my computer is shut down?
If the computer running a registered Ground2Cloud client is powered off for any reason (user or scheduled shutdown, restart, upgrade, crash, etc.) or goes to sleep, then the Ground2Cloud client restarts and attempts to reconnect when the computer is retsrated.
Ground2Cloud will not restart if the machine is rebooted into network-restricted, service-restricted, or "safe" mode.
While the computer is shutdown, attempts to make API calls to the endpoint or tunnel port may result in a connection timeout, an empty message, or an HTTP 500-class error, depending on network connectivity and type of shutdown.
Troubleshooting
How to I check the Ground2Cloud logs?
If you can start the Ground2Cloud GUI, then you can open the Logs tab to see the most recent log entries. Even if you can't understand all of their content, the presence of red or orange entries (these are entries listed with "warning" or "error" log levels) might indicate a known problem.
If you can't start the GUI, or if you want to look at less recent logs, the C:\Ground2Cloud\logs directory will contain more logging data to
look over. If you decide to contact Cloud Elements about your issue, you may be asked to read out or send over these log files; they contain
valuable information to help debug your problem.
How can I stop and start the Ground2Cloud service?
In the Windows Services control panel, you should see the service named Ground2Cloud. You should be able to stop and then start this service like any other Windows service, which may remedy lingering process issues. If the control panel complains that the service cannot be started, then you may need to contact Cloud Elements support to help further investigate the problem.
How can I uninstall / re-install Ground2Cloud?
Uninstalling and re-installing Ground2Cloud may remove some persistent errors you might be having, especially if you are upgrading Ground2Cloud to a newer version.
