---
title: "Using a Remote GSQL Client"
description: "Instructions on how to use a remote GSQL to connect to a TigerGraph instance."
component: "tigergraph-server"
version: "4.3"
module: "gsql-shell"
html_url: "/tigergraph-server/4.3/gsql-shell/using-a-remote-gsql-client"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/gsql-shell/using-a-remote-gsql-client"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/gsql-shell/using-a-remote-gsql-client.md"
---

[View as HTML](https://www.tigergraph.com/docs/tigergraph-server/4.3/gsql-shell/using-a-remote-gsql-client)

# Using a Remote GSQL Client

You can use the GSQL client to access a GSQL server on a different machine, including on a TigerGraph Cloud instance.

* [Connect to a remote server](https://www.tigergraph.com/docs/tigergraph-server/4.3/gsql-shell/using-a-remote-gsql-client.md#_connect_to_a_remote_server)
* [Connect to TigerGraph Cloud instance](https://www.tigergraph.com/docs/tigergraph-server/4.3/gsql-shell/using-a-remote-gsql-client.md#_connect_to_tigergraph_cloud_instance)

## Prerequisites

* The machine running the GSQL client needs to have Java 7.0 or later.
* For a self-managed remote server, the server machine allows the client machine to access port 14240.
* OpenSSL is needed on the client machine to get an SSL certificate from the TigerGraph Server or TigerGraph Cloud.

## Connect to a remote server

### Download the GSQL client

[Download the GSQL client for a TigerGraph solution version directly from this page](https://dl.tigergraph.com).

As an alternative to downloading, you can also copy the file `gsql_client.jar` from an existing installation to the client machine. The client is packaged as a Java jar file, `gsql_client.jar` located in the folder `<TigerGraph_root_dir>/app/<VERSION_NUM>/dev/gdk/gsql/lib/` on an existing TigerGraph installation.

### Obtain SSL certificate

If you have SSL enabled, you must obtain the TigerGraph server's public SSL certificate. Run the following Unix command, replacing `<ip_address>` with the IP address of your TigerGraph server, and replacing `<path_to_certificate>` with a filename for the certificate, such as `ssl_1.cert1`. Note that the port to access TigerGraph Server is 14240.

You need to install [openssl](https://www.openssl.org/) on your client machine to run this command.

```console
echo | openssl s_client  -connect <ip_address>:14240 |  sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > <path_to_certificate>
```

### Connect to the server

To connect to a remote server, your must provide the following to the GSQL client:

* The IP address of the GSQL server.
* Your TigerGraph user credentials.
* If you are running GSQL commands, the user you are logged in as must have the privileges to run them.
* If SSL/TLS encryption (e.g., HTTPS) is enabled on the server, you must [provide the server's SSL certificate](https://www.tigergraph.com/docs/tigergraph-server/4.3/gsql-shell/using-a-remote-gsql-client.md#obtain_ssl_cert_remote_server).

Run the following command to connect to the remote server:

```console
java -jar <path_to_client> \ (1)
  --cacert <path_to_certificate> \ (2)
  --ip <ip_address>:14240 \ (3)
  -u <username> (4)
```

| **1** | Replace `<path_to_client>` with the file path to the GSQL client. |
| --- | --- |
| **2** | If you have the SSL certificate of the remote server, you can replace `<path_to_certificate>` with the path to your SSL certificate (most common). Otherwise, you can use `--ssl` instead to use the default certificate. Note that `--ssl` will be overridden by `--cacert` option. If the remote server doesn't have SSL/TLS encryption enabled, you can omit these flags. |
| **3** | Replace `<ip_address>` with the IP address of your remote server. You can also [specify the IP address in a file and omit this flag](https://www.tigergraph.com/docs/tigergraph-server/4.3/gsql-shell/using-a-remote-gsql-client.md#_specify_server_ip_address_in_file). |
| **4** | Replace `<username>` with the username of the TigerGraph user you want to be logged in as. If you don't provide a `<username>`, the client uses the default user `tigergraph`. |

### Tip: Specify server IP address in file

You can create a one-line file called `gsql_server_ip_config` containing the IP address of the GSQL server.**This file needs to be in the same directory where you run GSQL.**

When there is a `gsql_server_up_config` file in the same directory where you run the GSQL client, the GSQL client uses the IP address stored in the file. You won't need to specify the IP address in the command.

### Tip: Define a Unix alias for command to run GSQL client

You can define a Unix alias to simplify the command to run the GSQL client:

```console
alias gsql="java -jar <path_to_gsql_client>"
```

After defining the preceding alias, running `gsql` is equivalent to running `java -jar <path_to_gsql_client>`.

## Connect to TigerGraph Cloud instance

Since TigerGraph Cloud uses a different [authentication scheme](https://www.tigergraph.com/docs/cloud/main/security/manage-org-users.md) from TigerGraph Server, the steps for using the GSQL client for a cloud solution are slightly different.

### Download the GSQL client

[Download the GSQL client for a TigerGraph solution version directly from this page](https://dl.tigergraph.com).

### Obtain SSL certificate

Run the following Unix command, replacing `<domain>` with the domain of your Cloud solution and replace `<path_to_certificate>` with the local path to place the certificate file. Note that the port to access TigerGraph Cloud is 443.

Find the domain of a Cloud solution by clicking on it in the solution view under "My Solutions."

You need to install [openssl](https://www.openssl.org/) on your client machine to run this command.

```console
echo | openssl s_client  -connect <domain>:443 |  sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > <path_to_certificate>
```

### Generate a secret

Use Admin Portal to generate a secret for your user account: [User Management](https://www.tigergraph.com/docs/gui/4.3/admin-portal/management/user-management.md)

### Connect to the cloud instance

Modify and run this command to connect to the TigerGraph Cloud instance:

```console
java -jar <path_to_client> \ (1)
  --cacert <path_to_certificate> \ (2)
  --ip <domain>:443 \ (3)
  -u __GSQL__secret -p <secret> (4)
```

| **1** | Replace `<path_to_client>` with the file path to the GSQL client. |
| --- | --- |
| **2** | Replace `<path_to_certificate>` with the file path to the local SSL certificate that you downloaded. |
| **3** | Replace `<domain>` with the domain of your Cloud solution. |
| **4** | Replace `<secret>` with the generated secret from the Admin Portal. |

## Filepath semantics

Data loading jobs always specify an input file location; logically the data should be on the server side, not on the client side. Because the command request comes from one machine and the target data file is on another machine, it no longer makes sense to use a relative path.

> [!NOTE]
> If a remote GSQL client invokes an instruction containing a relative path, the GSQL server considers the starting point of the path to be `<tigergraph_rootdir>/app/<VERSION_NUM>/dev/gdk/gsql` on the GSQL server.
> 
> It is strongly recommended that GSQL commands use absolute paths only when run remotely.

For example, if the data file `cf_data.csv` is in the folder `/home/tigergraph/example/cf/`, then the command to run the loading job might look like the following:

```console
java -jar gsql_client.jar 'RUN JOB load_cf USING FILENAME="/home/tigergraph/example/cf/cf_data.csv", SEPARATOR=",", EOL="\n"
```

## Example: Modifying a Bash script for a remote GSQL client

The GSQL Tutorials employ both GSQL and bash scripts to run the examples. Typically, each example case contains 3 GSQL command files (for schema creation, data loading, and querying) and one bash script to run all the parts together and to display status information. Below is a simplified version of the Collaborative Filtering (cf) bash script:

Bash script for Collaborative Filtering (cf) example

```console
#!/bin/bash
test='cf'
###
gsql 'DROP ALL'
gsql ../${test}/${test}_model.gsql
gsql 'CREATE GRAPH gsql_demo(*)'

# Loading
gsql -g gsql_demo ../${test}/${test}_load.gsql
## loading script contains this line:
## RUN JOB load_cf USING FILENAME="../cf/data/cf_data.csv", SEPARATOR=",", EOL="\n"

# Querying
gsql -g gsql_demo ../${test}/${test}_query.gsql
gsql -g gsql_demo INSTALL QUERY ALL
gsql -g gsql_demo 'RUN QUERY topCoLiked("id1", 10)'
```

The bash script will not run from a remote GSQL client unless a few changes are made:

* We need to invoke `java -jar gsql_client.jar` instead of `gsql`, and need to specify the server ip address.
* If we use the `gsql_server_ip_config` file, this file must be in the same folder as the command file.

The GSQL Tutorial has several folders, one for each example, which suggests making several config files.

Below is an approach that minimizes the changes required and maximizes standardization.

1. Do initial client setup. This is done only once.  
   1. Store `gsql_client.jar` in a standard location. For example, `/home/tigergraph/gsql_client/ gsql_client.jar` )  
   2. Create a file called `gsql_server_ip_config` containing the GSQL server's IP address, and store it a standard location, say `~/gsql_client/gsql_server_ip_config`.  
   Sample config file:/home/tigergraph/gsql\_client/gsql\_server\_ip\_config  
   ```text  
   123.45.67.255  
   ```  
   3. In the .bashrc file in your home directory, add an alias for gsql which points to the standard location:  
   ```console  
   alias gsql='java -jar ~/gsql_client/gsql_client.jar'  
   ```
2. Add a standard header to each bash script.  
Standard which makes 'gsql' work on remote clients  
```console  
alias gsql='java -jar gsql_client.jar'  
shopt -s expand_aliases  
ln -s ~/gsql_client/gsql_client.jar gsql_client.jar  
ln -s ~/gsql_client/gsql_server_ip_config gsql_server_ip_config  
```  
This header does the following:  
   1. Repeat the alias definition for the gsql command. The definition in `.bashrc` may not be visible here.  
   2. By default, bash scripts ignore aliases. Instruct the script to use aliases.  
   3. Define soft links from the current folder to the locations of the client jar and config file.
3. Change any relative paths to absolute paths. This is the only step that must be customized for each script.  
Here is the resulting script. Four standard lines were added to the beginning, and one line was edited in the `cf_load.gsql` file.

RUN\_cf\_remote.sh: Modified bash script for Collaborative Filtering (cf) example

```gsql
#!/bin/bash
alias gsql='java -jar gsql_client.jar'
shopt -s expand_aliases
ln -s ~/gsql_client/gsql_client.jar gsql_client.jar
ln -s ~/gsql_client/gsql_server_ip_config gsql_server_ip_config
test='cf'
###
gsql 'DROP ALL'
gsql ../${test}/${test}_model.gsql
gsql 'CREATE GRAPH gsql_demo(*)'

# Loading
gsql -g gsql_demo ../${test}/${test}_load.gsql
## loading script contains this line:
## RUN JOB load_cf USING FILENAME="/home/tigergraph/tigergraph/document/examples/tutorial_real_life/cf/data/cf_load.csv", SEPARATOR=",", EOL="\n"

# Querying
gsql -g gsql_demo ../${test}/${test}_query.gsql
gsql -g gsql_demo INSTALL QUERY ALL
gsql -g gsql_demo 'RUN QUERY topCoLiked("id1", 10)'
```
