> ## Documentation Index
> Fetch the complete documentation index at: https://syteca.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure SSH Connections for Linux Discovery

> Configure and troubleshoot SSH connections so Syteca can discover and onboard Linux accounts during Linux Discovery scans, using passwords or public SSH keys.

<Info>
  Not available in SaaS.
</Info>

[Account Discovery](/docs/pam/discovery/overview) uses SSH to find Linux accounts when running **Linux Discovery** rules, and to onboard them afterward. This page configures and troubleshoots those SSH connections.

The Linux scanner can discover (as set in the rule): all accounts (privileged, service, and application), only privileged accounts (manually created non-daemon accounts and `root`), and — in either case — accounts with public SSH keys.

## Configuration keys

<Warning>
  **As of the version introducing [Account Discovery Settings](/docs/administration/configuration/account-discovery-settings), these keys are configured in the Management Tool instead — the config-file keys below are removed on upgrade and no longer take effect.** The table below is kept for reference on older versions.
</Warning>

Add or change these in `EkranServer.Settings.config`, found in `C:\Program Files\Ekran System\Ekran System\Server` on the Application Server host.

| Key                                     | Default               | Purpose                                                                                                                                                   |
| --------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LinuxScanningConnectionTimeoutSeconds` | `20`                  | Max seconds spent connecting to one computer, for the Linux scanner and Unix (SSH) secret [rotation](/docs/pam/secrets/remote-password-rotation). Must be ≥ 1. |
| `LinuxScanningMaximumConnections`       | `processor_count * 4` | Max concurrent TCP/IP connections the scanner uses. Must be ≥ 1.                                                                                          |
| `LinuxScanningPort`                     | `22`                  | Port for the SSH TCP/IP connections used in scanning, onboarding, and rotation (Unix SSH secrets only).                                                   |

## General prerequisites

For Linux connections using either passwords or SSH keys:

<Steps>
  <Step title="Confirm sudo permissions">
    Check the account used for scanning/onboarding has sudo:

    ```bash theme={"system"}
    sudo whoami
    ```

    Output `root` means it has sudo permissions.

    <Note>
      You can scan accounts without sudo, but you cannot scan accounts with public SSH keys, or onboard any account type, without sudo.
    </Note>
  </Step>

  <Step title="Check the connection timeout">
    Confirm the timeout in `EkranServer.Settings.config` (the `LinuxConnectionTimeoutSeconds` key, default 20s). To increase it on the Application Server host, raise that value and set Max SYN Retransmissions to 8 (\~2 minutes):

    ```text theme={"system"}
    netsh interface tcp set global MaxSynRetransmissions=8
    netsh interface tcp show global
    ```
  </Step>

  <Step title="Confirm the Sudo service">
    Check that the **Sudo** service is installed on the target computer.
  </Step>

  <Step title="Exclude scanning user from secondary auth">
    If the scanning/onboarding account has [Secondary User Authentication](/docs/administration/clients/parameters/secondary-user-authentication#linux-clients) enabled on its Linux Client, add its username to **Exclude from secondary authentication** on the Configuration page's Authentication Options tab.
  </Step>

  <Step title="Confirm Bash is installed">
    ```bash theme={"system"}
    which bash
    ```

    Empty output means Bash isn't installed for that user.
  </Step>
</Steps>

## Using passwords for SSH connections

Open the sshd config and ensure password authentication is on:

```bash theme={"system"}
sudo nano /etc/ssh/sshd_config
```

Set `PasswordAuthentication` to `yes`, then reload SSH:

```bash theme={"system"}
sudo systemctl reload ssh
```

## Using public SSH keys for SSH connections

<Steps>
  <Step title="Enable public key authentication">
    In `/etc/ssh/sshd_config`, set `PubkeyAuthentication` to `yes`, then `sudo systemctl reload ssh`.
  </Step>

  <Step title="Configure passwordless sudo">
    Create a sudoers file for the user:

    ```bash theme={"system"}
    sudo nano /etc/sudoers.d/{username}-user
    ```

    Add this line (replace `{username}`):

    ```text theme={"system"}
    {username} ALL=(ALL) NOPASSWD:ALL
    ```

    Test it:

    ```bash theme={"system"}
    sudo -i
    ```

    If configured correctly, you switch to `root` without a password prompt.
  </Step>

  <Step title="Confirm the authorized_keys location">
    Check the SSH keys are at `{username}/.ssh/authorized_keys` on the target.
  </Step>
</Steps>

## Troubleshooting

Application Server logs can be [downloaded from the Management Tool](/docs/resources/troubleshooting/logs) or found in `C:\Program Files\Ekran System\Ekran System\ServerLogs`.

<AccordionGroup>
  <Accordion title="Failed to connect to the target host">
    The target is offline, or the timeout is too low. Turn the computer on, or increase `LinuxScanningConnectionTimeoutSeconds` in the config file.
  </Accordion>

  <Accordion title="Invalid user credentials specified">
    Wrong password, wrong/non-existent username, or wrong private key. Verify the credentials and test the connection over SSH, and confirm your public key is at `/home/{username}/.ssh/authorized_keys`.
  </Accordion>

  <Accordion title="Connection refused">
    The `sshd` service is offline/uninstalled, the SSH port is firewalled, the host is offline, or the timeout is too low. Install the OpenSSH client (`sudo apt-get install openssh-client`), start `sshd` (`sudo systemctl start sshd` after checking `systemctl status sshd`), add the Application Server host to the target's TrustedHosts, and allow the `LinuxScanningPort` in the firewall (`sudo ufw enable {port}/tcp`).
  </Accordion>

  <Accordion title="Hostname cannot be resolved">
    The target can't be reached by hostname. On the Application Server host, edit `C:\Windows\System32\drivers\etc\hosts` (open Notepad as administrator, set Files of type to All Files) and add a line like `127.0.0.1 domain.local`, then save.
  </Accordion>

  <Accordion title="Passwordless sudo is not configured">
    Connecting with a public key but passwordless sudo isn't set up. Create the sudoers file (`sudo visudo -f /etc/sudoers.d/{username}`), add `{username} ALL=(ALL) NOPASSWD: ALL`, and verify with `sudo -i`.
  </Accordion>

  <Accordion title="Other errors">
    * **Error executing an ssh command** — make sure the `sudo` utility is installed on the computer.
    * **Incorrect SSH key format / wrong passphrase** — confirm you can connect to the secret with the uploaded private key via the Connection Manager.
    * **Connection failed for an unknown reason** (for example, `ProxyException`) — verify credentials and test over SSH.
    * **Bash is not installed** — verify Bash for the connecting user (`command -v bash`), install it if missing (needs sudo), or add standard paths to `PATH` and `~/.profile` if installed but not found.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Account Discovery" icon="radar" href="/docs/pam/discovery/overview">
    Create and run Linux Discovery rules.
  </Card>

  <Card title="WMI & PowerShell scanning" icon="scan-search" href="/docs/pam/discovery/wmi-powershell">
    The equivalent setup for Windows Computer Discovery.
  </Card>
</CardGroup>