3.2. Connecting to a Server¶

There are several ways to connect your client to a running xGT server:

Use SSH Tunneling
Connect over an SSL-encrypted network connection
Connect to an open port on the server

The default port number is 4367. The xGT server listens on that port with a default hostname of “localhost”. Throughout this page, we assume the server platform has a DNS name of “my.example.com”.

3.2.1. Use SSH Tunneling¶

This strategy requires the user to have an SSH login account on the server platform running the xGT server process. To use this strategy, one must first establish an SSH connection, with tunneling, from their client laptop/desktop to the server platform:

$ ssh -L 4367:localhost:4367 my.example.com

The -L option says to map local port 4367 to the socket localhost:4367 on the server platform. Now, all that a Python script needs to do is the same as if it were connecting to an xGT server running on its local platform:

import xgt
server = xgt.Connection(host='localhost')

3.2.2. Connect Via SSL-encrypted Network Connection¶

In order to run a secure xGT server, it is necessary to configure the server in this way:

"system.usessl" : True,
"system.ssl_root_dir" : "/path/to/certs/root"

The /path/to/certs/root should point to the root directory where this directory subtree exists:

.
├── certs
│   ├── ca-chain.cert.pem
│   └── server.cert.pem
└── private
    └── server.key.pem

To connect to an xGT server using SSL, the client needs to pass the following flags to xgt.Connection(): ssl, ssl_root_dir, and ssl_server_cn. The ssl flag needs to be set to true. The ssl_root_dir flag should be set to the root directory containing the SSL certificates and private keys. The ssl_server_cn flag should be set to the common name for the server listed on the server side SSL certificate. The xGT client expects the following directory structure for SSL certificates and private keys:

.
├── certs
│   ├── ca-chain.cert.pem
│   └── client.cert.pem
└── private
    └── client.key.pem

Here is a sample Python script showing connecting to a server via an SSL-encrypted network:

import xgt
server = xgt.Connection(ssl = True, ssl_root_dir = "/path/to/client/certs/root/",
                        ssl_server_cn = "my.xGT.cn")

3.2.3. Connecting to an Open Port¶

Warning

This method is insecure without enabling SSL support. It is not recommended.

To use this connection strategy, the server must be configured with the DNS name of the server system as hostname. For example:

"system.hostname" : "my.example.com"

To connect to this server from anywhere on the internet, a Python script can do:

import xgt
server = xgt.Connection(host = 'my.example.com')

3.2.4. User Authentication¶

To connect to xGT and access any protected data, the connection to the xGT server must be authenticated. xGT’s authentication uses Linux’s Pluggable Authentication Modules to support multiple authentication sources. To create an authenticated session using the Python client, the user identification and credentials must be passed in:

conn = xgt.Connection(userid = "user01", credentials = "password01")

Once a user authenticates, the session is associated with that user’s security information as configured by the administrator.

When using a script or notebook, the Python getpass module can be used to securely authenticate a user’s password, prompting for a password input when run:

import getpass
conn = xgt.Connection(userid = "user01", credentials = getpass.getpass())

If authenticating into xGT with the client’s currently logged in UNIX user or LDAP user, the module may also be used to retrieve the userid:

import getpass
conn = xgt.Connection(userid = getpass.getuser(), credentials = getpass.getpass())