Skip to content

DOCS.md

Latest commit

 

History

History
247 lines (217 loc) · 6.32 KB

DOCS.md

File metadata and controls

247 lines (217 loc) · 6.32 KB
Raw
date 2019-08-04 00:00:00 +0000
title SSH
author appleboy
tags
deploy
publish
ssh
repo appleboy/drone-ssh
logo term.svg
image ghcr.io/appleboy/drone-ssh

Use the SSH plugin to execute commands on a remote server. The below pipeline configuration demonstrates simple usage:

- name: ssh commands
  image: ghcr.io/appleboy/drone-ssh
  settings:
    host: foo.com
    username: root
    password: 1234
    port: 22
    script:
      - echo hello
      - echo world

Example configuration in your .drone.yml file for multiple hosts:

  - name: ssh commands
    image: ghcr.io/appleboy/drone-ssh
    settings:
      host:
+       - foo.com
+       - bar.com
      username: root
      password: 1234
      port: 22
      script:
      - echo hello
      - echo world

Example configuration for multiple hosts with different port:

  - name: ssh commands
    image: ghcr.io/appleboy/drone-ssh
    settings:
      host:
+       - foo.com:1234
+       - bar.com:5678
      username: root
      password: 1234
-     port: 22
      script:
      - echo hello
      - echo world

Example configuration for command timeout, default value is 60 seconds:

  - name: ssh commands
    image: ghcr.io/appleboy/drone-ssh
    settings:
      host: foo.com
      username: root
      password: 1234
      port: 22
+       command_timeout: 2m
      script:
        - echo hello
        - echo world

Example configuration for execute commands on a remote server using ｀SSHProxyCommand｀:

  - name: ssh commands
    image: ghcr.io/appleboy/drone-ssh
    settings:
      host: foo.com
      username: root
      password: 1234
      port: 22
      script:
        - echo hello
        - echo world
+     proxy_host: 10.130.33.145
+     proxy_user: ubuntu
+     proxy_port: 22
+     proxy_password: 1234

Example configuration using password from secrets:

  - name: ssh commands
    image: ghcr.io/appleboy/drone-ssh
    settings:
      host: foo.com
      username: root
+     password:
+       from_secret: ssh_password
      port: 22
      script:
        - echo hello
        - echo world

Example configuration using ssh key from secrets:

  - name: ssh commands
    image: ghcr.io/appleboy/drone-ssh
    settings:
      host: foo.com
      username: root
      port: 22
+     key:
+       from_secret: ssh_key
      script:
        - echo hello
        - echo world

Example configuration for exporting custom secrets:

  - name: ssh commands
    image: ghcr.io/appleboy/drone-ssh
    environment:
      # MUST BE in UPPERCASE
      COMMIT:
        from_secret: commit
    settings:
      host: foo.com
      username: root
      password: 1234
      port: 22
+     envs:
        # can be in lowercase (uppercased in code)
        - commit
      script:
        - echo $COMMIT

Example configuration for stoping script after first failure:

  - name: ssh commands
    image: ghcr.io/appleboy/drone-ssh
    settings:
      host: foo.com
      username: root
      password: 1234
      port: 22
+     script_stop: true
      script:
        - mkdir abc/def/efg
        - echo "you can't see the steps."

Example configuration for passphrase which protecting a private key:

  - name: ssh commands
    image: ghcr.io/appleboy/drone-ssh
    settings:
      host: foo.com
      username: root
+     key:
+       from_secret: ssh_key
+     passphrase: 1234
      port: 22
      script:
        - mkdir abc/def/efg
        - echo "you can't see the steps."

Example configuration for forcing protocol to IPv4 only:

  - name: ssh commands
    image: ghcr.io/appleboy/drone-ssh
    settings:
      host: foo.com
      username: root
      password: 1234
      port: 22
+     protocol: tcp4
      script:
        - echo hello
        - echo world

Secret Reference

Key Description
ssh_username account for target host user
ssh_password password for target host user
ssh_passphrase The purpose of the passphrase is usually to encrypt the private key.
ssh_key plain text of user private key
proxy_ssh_username account for user of proxy server
proxy_ssh_password password for user of proxy server
proxy_ssh_passphrase The purpose of the passphrase is usually to encrypt the private key.
proxy_ssh_key plain text of user private key for proxy server

Parameter Reference

Key Description
host target hostname or IP
port ssh port of target host
protocol IP protocol to use: either tcp, tcp4 or tcp6
username account for target host user
password password for target host user
key plain text of user private key
key_path key path of user private key
envs custom secrets which are made available in the script section
script execute commands on a remote server
script_stop stop script after first failure
timeout Timeout is the maximum amount of time for the ssh connection to establish, default is 30 seconds.
command_timeout Command timeout is the maximum amount of time for the execute commands, default is 10 minutes.
proxy_host proxy hostname or IP
proxy_port ssh port of proxy host
proxy_protocol IP protocol to use for the proxy: either tcp, tcp4 or tcp6
proxy_username account for proxy host user
proxy_password password for proxy host user
proxy_key plain text of proxy private key
proxy_key_path key path of proxy private key

Execution failures and debug output

With sync: true, hosts run in order and the first failure stops subsequent hosts. In parallel mode (the default), all started hosts are allowed to finish or time out before the first reported error is returned. Errors include the affected host.

Debug mode uses godump to show a copy of the connection configuration. Non-empty SSH and proxy keys, passwords, and passphrases appear as [REDACTED]; unset credentials remain empty and other settings remain visible. The original configuration is unchanged. Forwarded environment variables are logged as NAME=[REDACTED]; their original values are still sent to the remote script. Debug command text and remote command output remain visible, so secrets written directly into scripts or printed by commands are not automatically masked.