Victron Venus OS Root Access: How to Enable SSH

Key Takeaways

• Root access allows advanced system modifications but carries significant risk, including bricking the device.
• Always understand the potential for rendering your GX device useless before proceeding with modifications.
• Firmware updates will reset root passwords and overwrite any modifications made to the root filesystem.
• Use the /data partition for persistent changes, such as SSH keys, as it survives firmware updates.

How do I enable root access on Victron Venus OS?

Enabling root access on Victron Venus OS involves several steps: setting the access level to Superuser, creating a root password, and enabling the SSH service. This process grants command-line access to the underlying Linux operating system of your GX device or Raspberry Pi running Venus OS. Proceed with caution, as incorrect modifications can lead to system instability or device failure.

Enabling Root Access and SSH on Venus OS

This section outlines the steps to gain root access and enable SSH for your Victron GX device or Raspberry Pi running Venus OS.

Step 1: Set Access Level to Superuser

Before you can set a root password, the access level on your Venus OS device must be elevated to Superuser.

1. Navigate to Settings > General on your GX device.
2. Set the Access Level to User and installer. The password for this level is ZZZ.
3. To change the Access Level to Superuser, the method varies by device interface:

• • For devices with a center pad (e.g., CCGX): Highlight Access Level on the General page, then press and hold the right button of the center pad until the Access Level changes to Superuser.
  • For the New UI: Select, drag down, and hold down the entire list of Access & Security menu entries for five seconds.
  • For touchscreens (e.g., Cerbo GX + GX Touch): Drag the menu down and hold for five seconds. Note that on a touchscreen, there is no "right button".

Step 2: Create a Temporary Root Password

Once Superuser access is enabled, you can set a root password.

1. Go to Settings > General > Set root password.
2. Create a new password. The password must be a minimum of 6 characters long.

Step 3: Enable SSH Service

To log in remotely, the SSH service must be enabled on your Venus OS device.

1. Navigate to Settings > General.
2. Enable SSH on LAN.
3. For Venus OS versions before v2.40, you also need to enable Remote Support, which activates the sshd service.

Step 4: Log In via SSH

With SSH enabled, you can now connect to your GX device from a computer.

1. Open a command-line interface (Terminal on Linux/macOS, or a client like PuTTY on Windows).
2. Use the command ssh root@<IP_ADDRESS_OF_GX_DEVICE>, replacing <IP_ADDRESS_OF_GX_DEVICE> with your device's IP address.
3. When prompted, enter the root password you created in Step 2.

Step 5: Install SSH Keys for Persistent Access (Recommended)

Using SSH keys provides a more secure and convenient way to access your device, and they persist across firmware updates.

1. After logging in with the root password, copy your public SSH key to ~/.ssh/authorized_keys on the GX device.
2. Using an SSH key for authentication has the advantage that it is not lost during a firmware update, as the keys are stored on the /data partition.
3. Once key authentication is confirmed to be working, you can optionally disallow root logins with a password by executing the command: echo 'root:*' | chpasswd -e.

Understanding Venus OS Partition Layout and Firmware Updates

Venus OS uses a specific disk partition layout that affects how modifications are handled, especially during firmware updates.

Partition Layout

By default, the rootfs (root filesystem) is mounted read-only. Changes made to the rootfs will be lost during a firmware update. This is because updates on Venus OS are image-based, meaning the complete rootfs is overwritten.

The /data partition is designed to be persistent. It is left untouched during image updates, making it suitable for storing custom scripts or configurations that you want to survive firmware updates. The Modifications enabled option, found in the General > Modification checks menu, relates to how the system handles custom scripts.

Note that the root password will be reset by a firmware update. This is because the passwd file is located on the rootfs, which is entirely replaced during an update. The root password being stored on the rootfs also causes it to be marked as modified.

Safety: Risks of Modifying Venus OS

Enabling root access and modifying Venus OS carries significant risks. It is possible to brick your GX device, rendering it useless and unrecoverable. If not fully bricked, modifications can lead to a state from which there is no documentation or official support on how to recover.

• Device Bricking: Incorrect modifications, especially to crucial system files, can prevent your device from booting.
• Loss of Support: Victron Energy does not provide support for issues arising from user modifications made with root access.
• Data Loss: Accidental removal of files crucial for the boot process, either on the boot partition or the rootfs, can cause the device to fail to boot.
• Firmware Update Overwrites: Any changes made directly to the rootfs will be lost when a firmware update is applied, as the entire rootfs is replaced.

The factory reset procedure, documented in the normal user manuals of GX devices, removes everything from the /data partition except for factory-installed files. However, it will not recover from all possible mistakes, especially if boot files are corrupted.

When to call a technician instead

Root access to Venus OS is intended for advanced users who understand Linux command-line operations and the potential consequences of system modifications. If you are unsure about any step or the implications of making changes, it is best to avoid enabling root access. Victron Energy does not offer support for issues caused by user modifications. If your device experiences problems not related to root access, consult your installer or Victron support channels.