User Tools

Site Tools


Venus OS: Root Access

This document explains how to access a GX device via SSH, or straight on the Serial Console, with the root user.

This document is part of the Venus OS developer documentation. The main document is the Venus OS wiki on github.

Warning about modifying the rootfs

Note that additions made to the rootfs are not safe during an update, as the complete rootfs is replaced during an update.

Of course it is always possible to disable automatic firmware updates. Also there is a data partition (/data), which will be left alone in the image updates.

Hooks to install/run own code at boot

Everything, except for information on /data, will be wiped after an update.

Therefor, the trick to make changes & modifications survive an update, is to put files you need on /data, make them be (re-)installed automatically on startup. This section describes how to do that.

If the files /data/rcS.local or /data/rc.local exists, they will be called early (rcS) and late (rc) during startup. These scripts will survive upgrades and can be used by customers to start their own custom software. Implementation details in this commit.

Also if venus-data.{tar.gz,tgz,zip} is found on removable storage (usb stick, sd-card) when booting, it will be unpacked into /data. Implementation details in this commit. Added per Venus v2.30~28.

You can test the 'update' with /opt/victronenergy/swupdate-scripts/ -update -force which will install the same version again, but in the other rootfs.

For details of the used update mechanism, see here:

Partitions and available disk space

On a GX Device, there are three partitions that matter:

  • rootfs partition one
  • rootfs partition two
  • the data partition

Only one of the two rootfs partitions will be in use. When doing a firmware update, it will be installed on the other, and the subsequent reboot will reboot the device onto that other partition.

The data partition is not touched during a firmware update, except maybe some migration scripts that run at boot.

When doing modifications, make sure both the data partition and the rootfs do not run out of space. We don't design or test for that situation.

With regards to the size of the data partition, thats easy to check using the df utility. But not so for the rootfs:

After logging into a GX device, and checking the free disk space on the rootfs(! thats not the data partition), you might get a bit disappointed at first. Don't worry too much, by design there will always be only 5% of free space.

The reason behind is that a firmware update replaces the full filesystem on the rootfs (as an image). And its then not expanded to the full available space of the partition reserved for the rootfs.

To see the full space, run /opt/victronenergy/swupdate-scripts/ It will expand the filesystem to use all of the available space.

For actual available diskspace on our GX Devices, see

To see what is doing, without having to log into your Venus OS, see it also here.

Note that a firmware update will replace all of the rootfs, as also explained above. Which implies that you'll need to run again after doing a firmware update.

1. Set access level to Superuser

To set the root password, first set the access level to Superuser:

  1. Go to Settings, General
  2. Set the Access Level to User and installer, the password is ZZZ
  3. Highlight Access Level (don't open the select page, ie. make sure you are in the General Page, not the Access Level page)
  4. Press and hold the right button of the center pad until you see the Access Level change to Superuser. Note: when working from the Remote Console, you need to use the right key on your keyboard. Pressing and holding the right button with your mouse won't work.

Now you have access to the super user features.

Note that on a touchscreen, such as a Cerbo GX + GX Touch, there is no “right button”. Instead, drag the menu down and hold it down for five seconds. Or, use Remote Console.

2. Create a root password

Go to Settings → General → Set root password. And create a root password.

Note that, for firmware version v2.00 and later, the root password will be reset by a firmware update. The reason is that the passwd file is on the rootfs, which is fully replaced by an update. More info here.

Our advice is to create a root password. But use it to login only the first time, and then install a public ssh key(s). Thereafter login with the keys.

3. Enable sshd and log in

To login via ssh, enable Remote Support (Settings → General). Besides enabling the reverse tunnel it also enables sshd. More info on Remote Support here.

To the login, enter the ip address of the GX device in a ssh client. Most Linux and Mac users will simply do this from the command line:

ssh root@

And a very commonly used client for Windows is Putty. For more info, look around on the Internet, there is plenty information available.

4. Working with ssh keys

Using a ssh key for authentication, instead of a root password, has the advantage that it isn't lost during a firmware update. The keys are stored on the /data partition.

First set the root password (once), use that to login, and then copy a public ssh key to ~/.ssh/authorized_keys.

sshd works with three authorized keys files:

  • ~/.ssh/authorized_keys ← you can use this freely
  • ~/.ssh/authorized_keys2
  • /usr/share/support-keys/authorized_keys

The third file contains the keys we use for Remote Support login.

5. Play time! Start executing commands

6. Connecting on the serial console


The serial console offers a straight connection from your computer. Not relying on TCP or anything else.

Its an alternative to connecting to the commandline over ssh.

Connecting to the serial console requires a USB interface, ie a USB to serial cable with proper pin-out. For example this one:

The serial consoles on all GX devices are configured to 115200 baud.

Serial console on GX device

All GX Devices have a dedicated serial console, except for the CCGX. Therefor its documented on a separate page:

CCGX Serial Console.

Serial Console on Cerbo GX

The serial console is located on the CPU board, header JP201. GND is pin 1, RX and TX are pins 4 and 5. Here is a picture showing a ADA Fruit Serial Console cable connected to it.

Make sure not to connect the red wire.

Serial Console on Venus GX

The serial console is located on the base-board, and can be accessed through the slot between that board and the Ethernet connector on the beaglebone-board.

White: TX of the Beaglebone - connect to RX on your cable Black: ground Green: RX of the Beaglebone - connect to TX on your cable

Make sure not to connect the red wire.

Here is a picture showing how, also using the adafruit serial console cable as referenced above:

Serial console on GX Card / Nanopi

The GX Card is the PCBA inside the MultiPlus-II GX and EasySolar-II GX product ranges. This photo shows the card, when unmounted from these inverter/chargers.

Maybe the pins are also accessible without dismantling it, maybe not. Note that all this is at your own risk, as everything on these pages is.

The serial console is the pinheader on the right of the photo. In the photo, there is an Adafruit serial console cable connected.

Serial console on Octo GX

The serial console is located on the base-board, and can be accessed with the top-board unmounted. With the serial console cable connected the top-board can be put back on again.

  1. Black: ground
  2. NC
  3. NC
  4. Green: RX of the Beaglecore - connect to TX on your cable
  5. White: TX of the Beaglecore - connect to RX on your cable
  6. NC

Make sure not to connect the red wire.

ccgx/root_access.txt · Last modified: 2021-03-29 14:04 by krenzke