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
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
6060114
Fix confusing wording about installation logs
ydirson Sep 24, 2025
99af74e
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
35 changes: 33 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,43 @@ 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 for simple problems access through the console as described
Copy link
Collaborator

@thomas-dkmt thomas-dkmt Sep 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

The wording could be a bit more natural, something like that:

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:

  1. Activate the network
  2. Enable the sshd service
  3. Set a root password of your choice

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

above can be sufficient, it can be necessary to collect the full
install log, kernel log and such large amount of data, which is quite
impractical unless you can just copy the files.

To enable ssh/scp access during installation, you can request on the
linux kernel command line the activation of the network, and enabling
of sshd service with a root password of your choice. For the common
case of setting up the network with DHCP, add the following to the
linux boot parameters:

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

You may select an alternative setup using `network_config` (which
Copy link
Collaborator

Choose a reason for hiding this comment

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

I suggest this wording:

You can also use the network_config parameter (which defaults to dhcp) to define an alternative network setup. Here’s how it works:

  • 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]

defaults to `dhcp`). Its usage summary is as follows (values you need
to provide are the ones in capital, brackets denote 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`
Copy link
Collaborator

@thomas-dkmt thomas-dkmt Sep 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Feel free to use Docusaurus' "Note" element:

:::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.
:::

if necessary, which can be useful when you need to setup a static IP
address.

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)

## Installation logs

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

Choose a reason for hiding this comment

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

Suggested change
On the installed system, the installer logs are kept 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).