actions/ssh
actions/ssh
3
0
Fork 0
mirror of https://gitea.com/actions/appleboy-ssh-action.git synced 2024-11-26 03:59:35 +01:00
Code Issues Projects Activity Pipelines

docu(restructure): update readme structure and add ed25519 ssh key instructions (#113)

Browse source
This commit is contained in:
h1dden-da3m0n 2021-04-03 23:59:44 +02:00 committed by GitHub
parent c7104ccac4
commit e59c0ee97a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 117 additions and 51 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

162
README.md
View file

@ -8,6 +8,42 @@
**Important**: Only support **Linux** [docker](https://www.docker.com/) container. **Important**: Only support **Linux** [docker](https://www.docker.com/) container.
## Input variables
See [action.yml](./action.yml) for more detailed information.
* `host` - ssh host
* `port` - ssh port, default is `22`
* `username` - ssh username
* `password` - ssh password
* `passphrase` - the passphrase is usually to encrypt the private key
* `sync` - synchronous execution if multiple hosts, default is false
* `timeout` - timeout for ssh to remote host, default is `30s`
* `command_timeout` - timeout for ssh command, default is `10m`
* `key` - content of ssh private key. ex raw content of ~/.ssh/id_rsa
* `key_path` - path of ssh private key
* `fingerprint` - fingerprint SHA256 of the host public key, default is to skip verification
* `script` - execute commands
* `script_stop` - stop script after first failure
* `envs` - pass environment variable to shell script
* `debug` - enable debug mode
* `use_insecure_cipher` - include more ciphers with use_insecure_cipher (see [#56](https://github.com/appleboy/ssh-action/issues/56))
* `cipher` - the allowed cipher algorithms. If unspecified then a sensible
SSH Proxy Setting:
* `proxy_host` - proxy host
* `proxy_port` - proxy port, default is `22`
* `proxy_username` - proxy username
* `proxy_password` - proxy password
* `proxy_passphrase` - the passphrase is usually to encrypt the private key
* `proxy_timeout` - timeout for ssh to proxy host, default is `30s`
* `proxy_key` - content of ssh proxy private key.
* `proxy_key_path` - path of ssh proxy private key
* `proxy_fingerprint` - fingerprint SHA256 of the proxy host public key, default is to skip verification
* `proxy_use_insecure_cipher` - include more ciphers with use_insecure_cipher (see [#56](https://github.com/appleboy/ssh-action/issues/56))
* `proxy_cipher` - the allowed cipher algorithms. If unspecified then a sensible
## Usage ## Usage
Executing remote ssh commands. Executing remote ssh commands.
@ -43,69 +79,87 @@ out: ***
============================================== ==============================================
``` ```
## Input variables ### Setting up a SSH Key
See [action.yml](./action.yml) for more detailed information.
* host - ssh host
* port - ssh port, default is `22`
* username - ssh username
* password - ssh password
* passphrase - the passphrase is usually to encrypt the private key
* sync - synchronous execution if multiple hosts, default is false
* timeout - timeout for ssh to remote host, default is `30s`
* command_timeout - timeout for ssh command, default is `10m`
* key - content of ssh private key. ex raw content of ~/.ssh/id_rsa
* key_path - path of ssh private key
* fingerprint - fingerprint SHA256 of the host public key, default is to skip verification
* script - execute commands
* script_stop - stop script after first failure
* envs - pass environment variable to shell script
* debug - enable debug mode
* use_insecure_cipher - include more ciphers with use_insecure_cipher (see [#56](https://github.com/appleboy/ssh-action/issues/56))
* cipher - the allowed cipher algorithms. If unspecified then a sensible
SSH Proxy Setting:
* proxy_host - proxy host
* proxy_port - proxy port, default is `22`
* proxy_username - proxy username
* proxy_password - proxy password
* proxy_passphrase - the passphrase is usually to encrypt the private key
* proxy_timeout - timeout for ssh to proxy host, default is `30s`
* proxy_key - content of ssh proxy private key.
* proxy_key_path - path of ssh proxy private key
* proxy_fingerprint - fingerprint SHA256 of the proxy host public key, default is to skip verification
* proxy_use_insecure_cipher - include more ciphers with use_insecure_cipher (see [#56](https://github.com/appleboy/ssh-action/issues/56))
* proxy_cipher - the allowed cipher algorithms. If unspecified then a sensible
### Setting up SSH Key
Make sure to follow the below steps while creating SSH Keys and using them. Make sure to follow the below steps while creating SSH Keys and using them.
The best practice is create the SSH Keys on local machine not remote machine. The best practice is create the SSH Keys on local machine not remote machine.
Login with username specified in Github Secrets. Generate a RSA Key-Pair: Login with username specified in Github Secrets. Generate a RSA Key-Pair:
<details>
<summary>rsa</summary>
<p>
```bash ```bash
ssh-keygen -t rsa -b 4096 -C "your_email@example.com" ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
``` ```
</p>
</details>
<details>
<summary>ed25519</summary>
<p>
```bash
ssh-keygen -t ed25519 -a 200 -C "your_email@example.com"
```
</p>
</details>
Add newly generated key into Authorized keys. Read more about authorized keys [here](https://www.ssh.com/ssh/authorized_keys/). Add newly generated key into Authorized keys. Read more about authorized keys [here](https://www.ssh.com/ssh/authorized_keys/).
<details>
<summary>rsa</summary>
<p>
```bash ```bash
cat .ssh/id_rsa.pub | ssh b@B 'cat >> .ssh/authorized_keys' cat .ssh/id_rsa.pub | ssh b@B 'cat >> .ssh/authorized_keys'
``` ```
</p>
</details>
<details>
<summary>ed25519</summary>
<p>
```bash
cat .ssh/id_ed25519.pub | ssh b@B 'cat >> .ssh/authorized_keys'
```
</p>
</details>
Copy Private Key content and paste in Github Secrets. Copy Private Key content and paste in Github Secrets.
<details>
<summary>rsa</summary>
<p>
```bash ```bash
clip < ~/.ssh/id_rsa clip < ~/.ssh/id_rsa
``` ```
</p>
</details>
<details>
<summary>ed25519</summary>
<p>
```bash
clip < ~/.ssh/id_ed25519
```
</p>
</details>
See the detail information about [SSH login without password](http://www.linuxproblem.org/art_9.html) See the detail information about [SSH login without password](http://www.linuxproblem.org/art_9.html)
### Example ### Example
Executing remote ssh commands using password. #### Executing remote ssh commands using password
```yaml ```yaml
- name: executing remote ssh commands using password - name: executing remote ssh commands using password
@ -118,7 +172,7 @@ Executing remote ssh commands using password.
script: whoami script: whoami
``` ```
Using private key #### Using private key
```yaml ```yaml
- name: executing remote ssh commands using ssh key - name: executing remote ssh commands using ssh key
@ -131,7 +185,7 @@ Using private key
script: whoami script: whoami
``` ```
Multiple Commands #### Multiple Commands
```yaml ```yaml
- name: multiple command - name: multiple command
@ -148,7 +202,7 @@ Multiple Commands
![result](./images/output-result.png) ![result](./images/output-result.png)
Multiple Hosts #### Multiple Hosts
```diff ```diff
- name: multiple host - name: multiple host
@ -164,7 +218,7 @@ Multiple Hosts
ls -al ls -al
``` ```
Multiple hosts with different port #### Multiple hosts with different port
```diff ```diff
- name: multiple host - name: multiple host
@ -179,7 +233,7 @@ Multiple hosts with different port
ls -al ls -al
``` ```
Synchronous execution on multiple hosts #### Synchronous execution on multiple hosts
```diff ```diff
- name: multiple host - name: multiple host
@ -195,7 +249,7 @@ Synchronous execution on multiple hosts
ls -al ls -al
``` ```
Pass environment variable to shell script #### Pass environment variable to shell script
```diff ```diff
- name: pass environment - name: pass environment
@ -218,7 +272,9 @@ Pass environment variable to shell script
_Inside `env` object, you need to pass every environment variable as a string, passing `Integer` data type or any other may output unexpected results._ _Inside `env` object, you need to pass every environment variable as a string, passing `Integer` data type or any other may output unexpected results._
Stop script after first failure. ex: missing `abc` folder #### Stop script after first failure
> ex: missing `abc` folder
```diff ```diff
- name: stop script if command error - name: stop script if command error
@ -247,7 +303,7 @@ err: mkdir: cannot create directory ‘abc/def’: No such file or directory
##[error]Docker run failed with exit code 1 ##[error]Docker run failed with exit code 1
``` ```
How to connect remote server using `ProxyCommand`? #### How to connect remote server using `ProxyCommand`?
```bash ```bash
+--------+ +----------+ +-----------+ +--------+ +----------+ +-----------+
@ -271,7 +327,7 @@ Host FooServer
ProxyCommand ssh -q -W %h:%p Jumphost ProxyCommand ssh -q -W %h:%p Jumphost
``` ```
How to convert to YAML format of GitHubActions. #### How to convert to YAML format of GitHubActions
```diff ```diff
- name: ssh proxy command - name: ssh proxy command
@ -290,7 +346,11 @@ How to convert to YAML format of GitHubActions.
ls -al ls -al
``` ```
Protecting a Private Key. The purpose of the passphrase is usually to encrypt the private key. This makes the key file by itself useless to an attacker. It is not uncommon for files to leak from backups or decommissioned hardware, and hackers commonly exfiltrate files from compromised systems. #### Protecting a Private Key
The purpose of the passphrase is usually to encrypt the private key.
This makes the key file by itself useless to an attacker.
It is not uncommon for files to leak from backups or decommissioned hardware, and hackers commonly exfiltrate files from compromised systems.
```diff ```diff
- name: ssh key passphrase - name: ssh key passphrase
@ -305,3 +365,9 @@ Protecting a Private Key. The purpose of the passphrase is usually to encrypt th
whoami whoami
ls -al ls -al
``` ```
## Contributing
We would love for you to contribute to `appleboy/ssh-action`, pull requests are welcome!
## License
The scripts and documentation in this project are released under the [MIT License](LICENSE)