SSH Configuration for Remote Host

You can use SmartAgentctl for deployments that require SSH authentication and proxy connectivity.

SSH Password Authentication

In addition to the existing private key authentication, you can use the SSH connections to support username and password authentication for environments where key-based authentication is unavailable or not required. To configure SSH using environment variable, see Configure SSH Using Environment Variable.

SSH Proxy Configuration for Remote Host

SSH connections can now route through HTTP or SOCKS5 proxies, enabling connectivity in network-restricted environments where direct SSH access is not available. To configure SSH connections through HTTP or SOCKS5 proxies, see Supported Proxy Types.

Configure SSH Using Environment Variable

  1. Update the remote.yaml file with the following to reference a password that is stored in an environment variable for better security:
    CODE 
    protocol:
  type: ssh
  auth:
    username: myuser
    type: password
    password_env_var: SSH_PASSWORD
    Here, username is required for SSH authentication and for type: password, you can also use the direct password (password) instead of environment variables (password_env_var). However, it is recommended to use the environment variables. If both are provided, password_env_var takes precedence.
    Note: The default authentication type is privatekey to maintain compatibility with existing configurations.
  2. Set the environment variable in the Smart Agent config.ini file before running smartagentctl:
    CODE 
    export SSH_PASSWORD="mypassword"
smartagentctl install --remote

Supported Proxy Types for Remote Host

HTTP Proxy

You can route the SSH connections through an HTTP proxy server:
CODE 
protocol:
  type: ssh
  auth:
    username: sshuser
    type: password
    password: sshpass
  proxy:
    type: http
    address: proxy.company.com:8080
    username: proxyuser
    password: proxypass
    plaintext: false  # optional, defaults to false
    insecure: false   # optional, defaults to false

Here, when:

  • plaintext is set to true, it connects to HTTP proxy without TLS encryption.
  • insecure is set to true, it skips TLS certificate verification for HTTPS proxies.

SOCKS5 Proxy

You can route SSH connections through a SOCKS5 proxy:
CODE 
protocol:
  type: ssh
  auth:
    username: sshuser
    type: privatekey
    private_key_path: /path/to/key
  proxy:
    type: socks5
    address: socks-proxy.company.com:1080
    username: proxyuser
    password: proxypass

Proxy Configuration

Field Type Required Description
type string Yes The proxy type. The value can be http or socks5
address string Yes The proxy server address with port. For example, proxy.example.com:8080.
username string No The proxy authentication username.
password string No The proxy authentication password.
plaintext boolean No (For HTTP proxy only) To use plain HTTP. The default value is false.
insecure boolean No (For HTTP proxy only) To skip TLS verification. The default value is false.

Configuration Consideration

  • address must include both hostname/IP and port.

  • Proxy authentication (username/password) is optional for both proxy types.

  • plaintext and insecure options are only valid for HTTP proxies

SSH Remote Host Configuration Examples

SSH with Password and HTTP Proxy

CODE 
remote_dir: /opt/smartagent
protocol:
  type: ssh
  auth:
    username: deployuser
    type: password
    password_env_var: DEPLOY_PASSWORD
  proxy:
    type: http
    address: corporate-proxy.company.com:8080
    username: proxyuser
    password: proxypass

hosts:
  - host: production-server-1.company.com
    port: 22
  - host: production-server-2.company.com  
    port: 2222

SSH with Private Key and SOCKS5 Proxy

CODE 
remote_dir: /home/appd
protocol:
  type: ssh
  auth:
    username: appd
    type: privatekey
    private_key_path: ~/.ssh/appd_deploy_key
  proxy:
    type: socks5
    address: jump-host.company.com:1080

hosts:
  - host: 10.0.1.100
  - host: 10.0.1.101