> For the complete documentation index, see [llms.txt](https://ljun20160606.gitbook.io/sshw/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ljun20160606.gitbook.io/sshw/config-detail.md).

# Config Detail

## Options

### config file

put config file in `~/.sshw` or `~/.sshw.yml` or `~/.sshw.yaml` or `./.sshw` or `./.sshw.yml` or `./.sshw.yaml`. or `sshw -f ./.sshw.yaml` to set filename. With alias `sshw -f ./.sshw.yaml dev`

config example: 

```yaml
- { name: dev server fully configured, user: appuser, host: 192.168.8.35, port: 22, password: 123456 }
- { name: dev server with key path, user: appuser, host: 192.168.8.35, port: 22, keypath: /root/.ssh/id_rsa }
- { name: dev server with passphrase key, user: appuser, host: 192.168.8.35, port: 22, keypath: /root/.ssh/id_rsa, passphrase: abcdefghijklmn}
- { name: dev server without port, user: appuser, host: 192.168.8.35 }
- { name: dev server without user, host: 192.168.8.35 }
- { name: dev server without password, host: 192.168.8.35 }
- { name: ⚡️ server with emoji name, host: 192.168.8.35 }
- { name: server with alias, alias: dev, host: 192.168.8.35 }
- name: server with jump
  user: appuser
  host: 192.168.8.35
  port: 22
  password: 123456
  jump:
  - user: appuser
    host: 192.168.8.36
    port: 2222


# server group 1
- name: server group 1
  children:
  - { name: server 1, user: root, host: 192.168.1.2 }
  - { name: server 2, user: root, host: 192.168.1.3 }
  - { name: server 3, user: root, host: 192.168.1.4 }

# server group 2
- name: server group 2
  children:
  - { name: server 1, user: root, host: 192.168.2.2 }
  - { name: server 2, user: root, host: 192.168.3.3 }
  - { name: server 3, user: root, host: 192.168.4.4 }
```

### callback

`callback-shells` is used to run command after ssh open a session. `error-pattern` is regex pattern that can be used to match message of error, it will return error if match successfully, but `sshw` receive output async, so if it could not match successfully, you can try wait some time.

`delay` mean before cmd, 'wait' mean after cmd

```yaml
- name: dev server fully configured
  user: appuser
  host: 192.168.8.35
  port: 22
  password: 123456
  callback-shells:
  - {cmd: 2, error-pattern: 'No such file'}
  - {delay: 1500, cmd: 0}
  - {cmd: 'echo 1'}
  - {cmd: 'exit 1', wait: 1000}
```

### ssh-agent

Support [ssh-agent](https://en.wikipedia.org/wiki/Ssh-agent)

Usage:

Add private to keychain

```bash
ssh-add ~/.ssh/.id_rsa
```

When jumper does not support channel, and you has no permission to modify `/etc/ssh/ssh_config`，or you won't save your private id\_rsa in jumper. sshw will connect to jumper by ssh-agent.

```yaml
- name: dev server fully configured
  user: appuser
  host: 192.168.8.35
  callback-shells:
  - {cmd: 'ssh 192.168.8.36'}
```

### copy file

Support cp file to remote from local like scp

```yaml
- name: dev
  user: appuser
  host: 192.168.8.35
  scps:
    - src: ~/test
      tgt: ./
      is-receive: false
```

| scp.options | description      | required |
| ----------- | ---------------- | -------- |
| src         | path             | true     |
| tgt         | path             | true     |
| is-receive  | send or revceive | false    |

### execs

Run command before ssh dial or after cancel ssh dial. `execs-pre` is before dial. `execs-stop` is after cancel ssh, but it's important to note that `execs-stop` only run when host does exist.

`execs-pre` also can set output as a variable into env.

If only needs to run command.

```yaml
- name: command-checklist
  execs-pre:
  - cmd: "echo command-checklist"
    var: echo_test
  - cmd: echo ${echo_test} 
  - cmd: "something else"
```

If run command after cancel ssh.

```yaml
- name: tell-some
  host: localhost
  callback-shells:
  - {cmd: 'echo login localhost'}
  - {cmd: 'exit 0'}
  execs-stop:
  - cmd: 'echo exit ssh'
```

### template

Environment variable could be read if the value is string, use `${param1,param2:defaultValue}`, it would be rendered by any one which is not empty value of `param1` `param2`. Support escape, read as literal `${foo}` if use `\${foo}`.

```yaml
- name: ${name}
  execs-pre:
  - {cmd: 'echo ${content} localhost'}
```

### merge

Merge config A to B. Only compare name and do override, otherwise it is complex. Also can use `-f` to specify persistent config.

```
sshw merge ./other.yaml
```

If doesn't want a name to be merged, use `merge-ignore: true`

```yaml
- name: foo
  merge-ignore: true
```

If config is a bookmark that has name and children only. It will be merged with children.

config A

```yaml
- name: foo
  children:
    - name: bar
      ...
```

config B

```yaml
- name: foo
  children:
    - name: car
      ...
```

config merged

```yaml
- name: foo
  children:
    - name: bar
      ...
    - name: car
      ...
```

### keyboardInteractive

Answer according to the matching questions. if question contains what we set question, it will be match. if set empty question, it means match all.

```yaml
- name: server with jump
  user: appuser
  host: 192.168.8.35
  keyboard-interactions:
  - question: your name
    answer: foo
```

## Global config

path`~/.config/sshw/config.yaml`, match same `host`, auto set `.sshw.yaml` properties `user` `port` `password` `keyboard-interactions`

## Ssh config

path`~/.ssh/config`, match same pattern `host`, auto replace  `host` of `.sshw.yaml`with `HostName`