Setup SSH in Instance

This endpoint reconfigures or re-initializes the SSH access parameters for a target Orion Series instance using its unique Instance ID. While secure shell access is automatically configured during initial instance launching, this endpoint allows developers to programmatically trigger an SSH service setup or repair command on the underlying virtual host.

Setup SSH in Instance - Overview

The Orion Series SSH Setup API allows authenticated users to configure or reconfigure the SSH connection for a specific Orion instance using its instance ID.

SSH is automatically configured when an Orion instance is launched. However, this endpoint can be used to reconfigure the SSH connection if needed.

When the request succeeds, the API returns a confirmation message and an SSH command that can be used to connect to the instance. Allow a few minutes after submitting the request before attempting to connect.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/orion/ssh/setup
Full URL	https://cloud.dataoorts.com/api/v1/orion/ssh/setup
Authentication	Bearer Token
Content Type	application/json
Response Format	JSON

Authentication

This endpoint requires a valid Dataoorts Unify API key.

Include your API key in the Authorization header using the Bearer authentication scheme.

HTTP

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Generate or manage your API key through the Dataoorts Unify API.

Keep your API key confidential and never expose it in public repositories or client-side applications.

Request Parameters

The request body must be sent as JSON.

Parameter	Type	Required	Description
instance_id	Integer	Yes	The ID of the Orion instance for which you want to configure or reconfigure SSH access.

Provide the ID of intended Orion instance and verify that the identifier is correct before submitting the request.

Request Examples

cURL - Use the following command to configure SSH for a Nova Series instance:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/orion/ssh/setup" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "instance_id": 50
  }'

Replace YOUR_API_KEY and the example instance ID with your actual values.

Python Example Implementation

The following example uses the requests library to submit an SSH setup request and display the returned SSH connection command.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/orion/ssh/setup"


def setup_orion_ssh(
    api_key: str,
    instance_id: int,
) -> dict:
    """
    Configure or reconfigure SSH for an Orion instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        instance_id: The ID of the Orion instance.

    Returns:
        dict: The JSON response containing the setup result
              and SSH connection command.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the response cannot be decoded as JSON.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "instance_id": instance_id,
    }

    response = requests.post(
        API_URL,
        headers=headers,
        json=payload,
        timeout=60,
    )

    response.raise_for_status()

    try:
        return response.json()
    except requests.exceptions.JSONDecodeError as exc:
        raise ValueError(
            "The API returned an invalid JSON response."
        ) from exc


if __name__ == "__main__":
    api_key = os.getenv("DATAOORTS_API_KEY")

    if not api_key:
        raise RuntimeError(
            "Set the DATAOORTS_API_KEY environment variable."
        )

    try:
        result = setup_orion_ssh(
            api_key=api_key,
            instance_id=50,
        )

        print("Status:", result.get("status"))
        print("Message:", result.get("message"))
        print("SSH Command:", result.get("ssh_command"))

    except requests.exceptions.RequestException as exc:
        print(f"API request failed: {exc}.")

    except ValueError as exc:
        print(f"Invalid API response: {exc}.")

Set your API key before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python setup_orion_ssh.py

Windows PowerShell

PowerShell

$env:DATAOORTS_API_KEY="YOUR_API_KEY"
python setup_orion_ssh.py

Replace 50 with the ID of the Orion instance for which you want to configure SSH.

Example Success Response

When the SSH setup request succeeds, the API returns a JSON response similar to the following:

JSON

{
  "message": "SSH configuration command sent for IP 204.12.171.93, Wait few minutes before connecting again to instance.",
  "ssh_command": "ssh [email protected]",
  "status": "success"
}

The returned IP address, SSH command, and message depend on the instance and the result of the request.

Response Fields

Field	Type	Description
status	String	Indicates result of API request. A successful response returns success.
message	String	A confirmation message indicating that the SSH configuration command was sent and advising you to wait a few minutes before connecting.
ssh_command	String	The SSH command returned by the API for connecting to the instance.

Understanding the SSH Setup Process

After submitting the request:

1. Dataoorts API processes the SSH setup request for the specified instance.
2. The API returns a confirmation message and the SSH command.
3. Allow a few minutes for the SSH configuration process before attempting to connect.
4. Use the returned ssh_command to initiate the SSH connection.

For example, the returned command may look like this:

Bash

ssh [email protected]

Run the command in a terminal environment that supports SSH.

A successful API response confirms that the SSH configuration command was sent. It does not necessarily mean that the instance is immediately ready to accept SSH connections.

Important Notes

1. Automatic SSH Configuration: SSH is automatically configured when an Orion instance is launched. Use this endpoint when SSH needs to be configured or reconfigured.

2. Correct Instance ID: Verify the instance_id before submitting the request to ensure that the intended instance is targeted.

3. Allow Time Before Connecting: Wait a few minutes after the request succeeds before attempting to establish an SSH connection.

4. Use the Returned Command: Use the ssh_command value returned by the API to connect to the instance.

5. Protect Access Information: Avoid exposing API keys or other sensitive access information in public repositories, application logs, or unauthorized environments.

6. Security Notice: For enhanced security, it is strongly recommended that you change the default SSH password immediately after establishing your initial connection to the instance.

Error Handling

If the request fails, the API may return an unsuccessful HTTP status code and a JSON response containing an error message.

Your application should handle authentication failures, invalid instance IDs, network errors, request timeouts, server errors, and unexpected response formats. The exact error codes and response messages depend on the API response.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. Do not assume that every response contains the same fields as the successful response shown above.

Get Help and Support

For assistance with Orion SSH configs or API integration, Contact our support team at [email protected].