Skip to content

Install troubleshooting with ssh #392

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+31 −2
Open

Install troubleshooting with ssh #392

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6243dc9
Fix confusing wording about installation logs
ydirson Sep 24, 2025
b2c64a4
Document how to access the installer using ssh
ydirson Sep 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 31 additions & 2 deletions docs/troubleshooting/installation-upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,41 @@ When asking for help about installation errors, providing this file increases yo

The target installation partition is mounted in `/tmp/root`.

### Getting remote access to host during installation

While the console access method described above may be sufficient for simple issues, collecting full logs (install logs, kernel logs, etc.) often requires copying large amounts of data, which is impractical without direct file access.

To enable SSH/SCP access during installation, you can use the Linux kernel command line to:

- Activate the network
- Enable the sshd service with a root password of your choice

For the most common case (setting up the network via DHCP), add the following parameters to the Linux boot section:

```
network_device=all sshpassword=YOURCHOICE
```

You can also use the `network_config` parameter (which defaults to `dhcp`) to define an alternative network setup. Here are some template examples; replace the capitalized values with your own settings, square brackets ([]) indicate optional parameters:

```
network_config=dhcp[:vlan=VLAN]
network_config=static:ip=IP;netmask=NETMASK[;gateway=GW][;dns=DNS1[,DNS2]][;domain=DOMAIN][;vlan=VLAN]
```

:::note
you can specify an interface name such as `eth1` instead of `all` if necessary, which can be useful when you need to setup a static IP address.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're not starting the sentence with a capital letter?

:::

The ssh server will be available once the network is up. If you are unsure which DHCP address was obtained, you can use the shell console as described above to look it up using `ip a`. You can then connect as `root` using the password you provided on the commandline.


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be useful to also explain:

  1. When the SSH server becomes available
  2. How to connect (which user, which hostname/IP - that's obvious but it doesn't hurt being explicit, which password - same)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand the need for "how to find the IP address when using DHCP", but I fear giving too many obvious details will just add noise to the doc. Doing as suggested, see the result for yourself.

## Installation logs

The installer writes in `/var/log/installer/`.
On the installed system, installer logs are kept in `/var/log/installer/`.

The main log file is `/var/log/installer/install-log`.

## Debugging the installer

You can [build your own installer](../../project/development-process/ISO-modification).
You can [build your own installer](../../project/development-process/ISO-modification).