Skip Navigation

Horizons Command-Line Access

2025-Sep-29

Horizons Command-line Interface … Now with Encryption & Authentication

To satisfy NASA IT requirements, the Horizons interactive command-line interface, previously accessed in clear-text with the command “telnet ssd.jpl.nasa.gov 6775”, is being replaced by something functionally identical but with added TLS encryption and optional PKI authentication.

This mechanism can also resolve firewall problems and avoid the need to set up and carry forward firewall exceptions to still allow direct terminal access.

To use this option, install, configure, and run the open source ‘stunnel’ application on your local machine as a client. It could take about one minute and typing five commands to be up and running, but of course longer to read instructions and understand the context.

‘stunnel’ is available as a free download for Windows, MacOS, iOS, Android, UNIX/Linux, and many other operating systems, if not already installed on the machine by default. The ‘stunnel’ application is not developed, managed, or distributed by JPL.

See the system compatibility list here: https://www.stunnel.org/platforms.html

Download stunnel here (if necessary): https://www.stunnel.org/downloads.html

Latest Horizons-specific ‘stunnel’ client configuration file: https://ssd.jpl.nasa.gov/ftp/ssd/horizons_stunnel_client.conf

Overview

Once installed, configured, and running on the user’s machine, ‘stunnel’ waits for internal connections on the users’ local machine, initiated by the user command:

telnet localhost 6775

or, equivalently (and possibly required on some systems):

telnet 127.0.0.1 6775

When this connection is detected, the local ‘stunnel’ application contacts the ‘stunnel’ running on the remote Horizons server at JPL, which negotiates an encryption protocol and optionally authenticates its identity to the users’ client by comparing signed encryption certificates. If everything checks out, the connection is forwarded to Horizons.

All communications between the user (client) and Horizons (server) are then passed through this encrypted channel, with ‘stunnel’ on both ends managing the encryption/decryption, passing clear-text to both Horizons and the user.

No difference in the Horizons interface is visible to the user or Horizons. Only the data passing over the Internet is encrypted. Therefore, existing scripts and automation require no alteration beyond the connection command.

Follow the installation instructions that come with the ‘stunnel’ download specific to your operating system, then use the Horizons-specific configuration file available here: https://ssd.jpl.nasa.gov/ftp/ssd/horizons_stunnel_client.conf

Installation details for ‘stunnel’ differ slightly based on operating system, but the variations usually relate to:

The instructions below typically refer to an example system running Red Hat Enterprise Linux. Tips for other operating systems are given where known.

Set-up

Installation requires root, administrator, or sudo permission. If you prefer, or if you have have insufficient file-system permissions, you might ask your local system administrator to do the installation.

  1. Install the ‘stunnel’ software on your local machine if it isn’t already there. Under Red Hat Linux, one can issue the command:

    sudo dnf install stunnel

    If you are running the ‘brew’ package management system under MacOS, the following command will install ‘stunnel’ from a terminal window:

    brew install stunnel

    If your MacOS system has no ‘telnet’ command, it can also be installed using brew:

    brew install telnet

    Otherwise, download the ‘stunnel’ version appropriate to your operating system from the ‘stunnel’ developer’s site and follow the installation instructions: https://www.stunnel.org/downloads.html

  2. Once the software is installed, download the Horizons client configuration file directly from JPL: https://ssd.jpl.nasa.gov/ftp/ssd/horizons_stunnel_client.conf

    For Internet-attached systems that have the ‘curl’ or ‘wget’ commands, the configuration file can be retrieved using terminal commands such as:

    curl -s https://ssd.jpl.nasa.gov/ftp/ssd/horizons_stunnel_client.conf -o horizons_stunnel_client.conf

    or

    wget https://ssd.jpl.nasa.gov/ftp/ssd/horizons_stunnel_client.conf

    Check the files after download to be sure the right thing transferred and it is not, for example, an error message.

    Alternatively, the file can be downloaded by saving from a browser window.

  3. OPTIONAL: If you want to activate server authentication (in addition to encryption) and require the Horizons server to prove its identity when connecting (by comparing signed encryption certificates from trusted Certificate Authorities (CAs)), edit the just-downloaded horizons_stunnel_client.conf text file according to the instructions in that file.

    The edits amount to specifying the location of an existing CA public keys file on your system (discussed below) and uncommenting four lines in the configuration file to activate authentication.

    Server authentication adds some complexity: you must determine where trusted Certificate Authority public keys are stored on your local machine and the certificates typically expire and are potentially updated every year or less.

    The goal of authentication is to prevent connecting to a fake server, or preventing “man-in-the-middle” situations in which a third party inserts into the communication stream, substituting encryption keys, and then relaying possibly altered data in either direction.

    However, this is mostly an issue for web servers, which transmit their code to the remote browser for execution. This makes it relatively easy to copy a web-site and put it up somewhere else, making it possible to capture input accounts, passwords, banking details, etc., if users can be redirected to the fake site without realizing it.

    By contrast, spoofing the Horizons interactive command-line interface is relatively painful since the system does not transmit its source code, can’t be set-up elsewhere, is an interactive command-line that functions in real-time, and doesn’t exchange any sensitive private data like passwords, accounts, or money.

    In addition, if the terminal interface is used for scripted automation (a deprecated approach for which the API interface is now recommended, see https://ssd-api.jpl.nasa.gov/doc/horizons.html ), more time and system resources may be required to repeatedly establish certificate-authenticated connections. Further, some users may not want or be able to run ‘stunnel’ on their local systems.

    However, since browsers are the most typical interface, many organizations mandate authentication and encryption as a generic policy, a pre-condition for connection & usage to everything on the Internet. So the option is offered here.

    Note that even if you don’t turn on authentication and accept the default “off” option, the session will still be encrypted with a TLS cipher negotiated during the ‘stunnel’ connection handshake. If you don’t need any of that, the clear-text command-line interface will remain for some period of time without any encryption, authentication, or ‘stunnel’ installation overhead. However, it will eventually be removed.

    If you intend to use authentication, edit the ‘CAfile’ entry in horizons_stunnel_client.conf file that was downloaded from JPL to point to the public certificate file on your system.

    For Red Hat Enterprise Linux, trusted CA public keys in PEM format are in this file:

    /etc/pki/tls/certs/ca-bundle.crt

    MacOS CA public keys are automatically installed by brew along with ‘stunnel’ and the openssl package that comes with it and are here (with a variation depending on CPU):

    Intel CPU : /usr/local/etc/ca-certificates/cert.pem
    Apple M1+ silicon: /opt/homebrew/etc/ca-certificates/cert.pem

  4. Once configuration edits (if any) are made, copy the horizons_stunnel_client.conf configuration file to the ‘stunnel’ working directory created during installation.

    Under Red Hat Linux, this is: /etc/stunnel

    Under MacOS with a ‘brew’ package manager installation, the equivalent directory differs based on type of CPU:

    Intel CPU : /usr/local/etc/stunnel/
    Apple M1+ silicon: /opt/homebrew/etc/stunnel/

    … but after copying, additionally create a symbolic link with the terminal command:

    Intel CPU : ln -s /usr/local/etc/stunnel/horizons_stunnel_client.conf /usr/local/etc/stunnel/stunnel.conf
    Apple M1+ silicon: ln -s /opt/homebrew/etc/stunnel/horizons_stunnel_client.conf /opt/homebrew/etc/stunnel/stunnel.conf

    This symbolic link is needed later for MacOS if you intend to set up ‘stunnel’ as a Launch Agent that automatically starts when you login.

Usage

  1. The client service can then be started (Red Hat Enterprise Linux) by typing

    sudo stunnel /etc/stunnel/horizons_stunnel_client.conf

    Under MacOS, when set-up via ‘brew’ package manager as above, start with:

    stunnel

    If all is well, the ‘stunnel’ asynchronous process will start and a new terminal prompt will appear. You may then establish an encrypted connection to Horizons with the terminal command:

    telnet localhost 6775
    or
    telnet 127.0.0.1 6775

    This connects your terminal window to the ‘stunnel’ process running on your machine, waiting for such connections. ‘stunnel’ then contacts the Horizons server as described in the overview above.

    If this fails, it is possible you are behind a firewall that blocks use of port 6770 for outgoing traffic. If so, see section 7 below on how to share a different, already-existing open port (multiplex). Or ask your local IT administration to allow outbound tcp connections from your machine to ssd.jpl.nasa.gov:6770. Since it will be a TLS encrypted and PKI authenticated connection indistinguishable from HTTPS browser activity, they may be much more willing to permit it than the clear-text port. If any browser or other TLS/SSL connections are allowed on the machine, this port’s I/O isn’t any different.

    When done with the Horizons connection, you can leave ‘stunnel’ running (at least until the next reboot) for future connections. It requires almost no computer resources while listening for connection requests.

    Alternatively, you can halt ‘stunnel’ with this Linux command (or the equivalent on your non-Linux system):

    sudo kill -9 `pidof stunnel`

    More generically under Linux/UNIX/MacOS versions without a ‘pidof’ command:

    sudo kill -9 `ps -A | grep stunnel | awk '{print $1}'

    If you want to change the configuration later (for example, turn authentication off or on), stop the service, edit the horizons_stunnel_client.conf file and restart the service for the change to take effect.

  2. After installation, if you want to define ‘stunnel’ as a daemon (or Launch Agent service under MacOS) that starts up in client mode automatically, and is always running so you can connect to Horizons anytime without thinking about ‘stunnel’, first stop/kill any running instance as described above.

    The details on setting this up will differ for each operating system. Check the installation instructions downloaded with ‘stunnel’ or your local system administrator.

    Under Red Hat Enterprise Linux (RHEL):

    sudo kill -9 `ps -A | grep stunnel | awk '{print $1}'`;
    sudo cp /usr/lib/systemd/system/stunnel.service /etc/systemd/system/horizons_stunnel_client.service;
    sudo systemctl enable stunnel@horizons_stunnel_client.service --now

    If you need to restart the service when it is already running,

    sudo systemctl restart stunnel@horizons_stunnel_client

    The command must use the configuration file name prefix (horizons_stunnel_client), which must be in the /etc/stunnel directory that was created during installation.

    Under MacOS, with ‘stunnel’ installed using the ‘brew’ package manager, the following terminal commands will start and enable future automatic start of ‘stunnel’ client service upon login:

    kill -9 `ps -A | grep stunnel | awk '{print $1}'`;
    brew services start stunnel

    The following command will cancel it (and remove automatic start):

    brew services stop stunnel

    Again, details like directory and the exact process for creating and managing automatic start-up will vary depending on your operating system and installation.

    We don’t have access to all operating system variations so cannot provide assistance or debug operating system-specific details. So if there are questions or problems, check with the ‘stunnel’ instructions for your platform, or your local system administrator. The ‘stunnel’ web-site is a good source of information: https://www.stunnel.org/

  3. The telnet protocol used to access the Horizons command-line interface may be blocked by many institutions due to its assumed clear-text approach, concern over account and password visibility, or its use of non-standard port 6775 normally not familiar to the operating system.

    However, Horizons doesn’t use accounts or exchange password data, and ‘stunnel’ TLS/SSL/PKI addresses the encryption and authentication issues of clear-text.

    If your outgoing connection remains blocked, ‘stunnel’ can also be used to address the familiarity issue and connect using any open outgoing local port, especially those which may already be open and approved for TLS/SSL traffic (ports 443, 992, 465, 563, etc.).

    In the client configuration file, change the line …

    accept = 127.0.0.1:6775

    … to have ‘stunnel’ listen for connection requests on the locally available alternate port instead of 6775.

    If the open port is used by some other service on the local machine, such as the example ports listed above, it is necessary to multiplex the port with tools like ‘sslh’ to successfully share the port: https://www.rutschle.net/tech/sslh/README.html

    The ‘sslh’ tool is part of many Linux/UNIX distributions.

    ‘stunnel’ TLS/SSL data packets are indistinguishable from browser traffic and port 443 (used for HTTPS web-browser activity) is open on most machines, as are several other typically TLS-approved ports. Only traffic-cop software like ‘sslh’ is required to ensure the encrypted TLS/SSL packets get delivered to the right applications sharing the port.

    Multiplexing port 443 with ‘stunnel’ and ‘sslh’ would allow use of an already open browser port with Horizons ‘stunnel’ traffic simultaneously. This has the benefit of not requiring your institution to set up special firewall exceptions and configurations or remember to carry them forward them into the future. Check with your institutional IT for the preferred approach.