ccgx:root_access
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
ccgx:root_access [2020-05-28 15:49] – [Available disk space] mvader | ccgx:root_access [2024-01-09 16:10] – [6.6 Ekrano GX] dfaber | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Venus OS: Root Access ====== | ====== 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. | + | ===== 1. Introduction ===== |
+ | |||
+ | This document explains how to access a GX device via SSH, or straight on the Serial Console, with the root user. It also covers customizing and hardening a GX device against nonauthorised access. | ||
This document is part of the Venus OS developer documentation. The main document is [[https:// | This document is part of the Venus OS developer documentation. The main document is [[https:// | ||
- | ==== 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. | + | Do note that, while we try to maintain to provide all mentioned functionality |
- | ==== Hooks to install/run own code at boot ==== | + | ===== 2. Warning about modifying the rootfs ===== |
- | Everything, except for information on /data, will be wiped after an update. | + | __1. Your changes can be lost during a firmware update__ |
- | Therefor, | + | Changes made to the rootfs will be lost in case of a firmware update. The complete rootfs is overwitten during |
- | 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 | + | 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, |
- | Also if venus-data.{tar.gz, | + | __2. It is possible to brick your GX device__ |
+ | |||
+ | For those unfamiliar with the term: Bricking means rendering it useless and unrecoverable. Chances of this are small (depending on what you do), but its certainly possible. And if not fully bricked, then at least in a state from which there is no documentation nor support on how to recover. | ||
+ | |||
+ | Note that a solution to this is to do Venus OS experiments on a RaspberryPi rather than a real GX device. The advantage of a raspberrypi is that you can always start from scratch, by re-imaging the sdcard. And the other is that it (the pi) is a low cost device. [[https:// | ||
+ | |||
+ | The factory reset procedure, as documented in the normal user manuals of the GX devices, removes everything from the data partition, except for the factory installed files. This will recover from issues caused by problems on the data partition, such as it being full or invalid settings or custom scripts. | ||
+ | |||
+ | But it will not recover from all possible mistakes that can be made. Some examples: | ||
+ | |||
+ | - if you accidentally remove files crucial for the boot process, either on the boot partition or the rootfs, then the device won’t boot anymore. The above mentioned factory reset feature depends on at least certain parts of the system booting up properly. More specifically, | ||
+ | - if you remove the files in / | ||
+ | |||
+ | ===== 3. Root access ===== | ||
+ | |||
+ | ==== 3.1 Set access level to Superuser ==== | ||
+ | To set the root password, first set the access level to Superuser: | ||
+ | - Go to Settings, General | ||
+ | - Set the Access Level to User and installer, the password is '' | ||
+ | - Highlight Access Level (don't open the select page, ie. make sure you are in the General Page, not the Access Level page) | ||
+ | - 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, | ||
+ | |||
+ | ==== 3.2 Create a temporary root password ==== | ||
+ | |||
+ | Go to //Settings -> General -> Set root password//. And create a temporary 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 [[https:// | ||
+ | |||
+ | Our advice is to create a complex root password. But use it to login only the first time, and then install a public ssh key(s). Thereafter login with the keys. If key authentication works, you can | ||
+ | safely disallow root logins with a password with '' | ||
+ | |||
+ | The password needs to be 6 characters long, minimum. | ||
+ | ==== 3.3 Enable sshd and log in ===== | ||
+ | |||
+ | To login via ssh, enable SSH on LAN (//Settings -> General//). On Venus versions before v2.40, you need to enable Remote Support, which also enables sshd. More info on Remote Support [[https:// | ||
+ | |||
+ | 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@192.168.1.23 | ||
+ | |||
+ | And a very commonly used client for Windows is [[http:// | ||
+ | |||
+ | ==== 3.4 Installing ssh keys ==== | ||
+ | |||
+ | Using a ssh key for authentication, | ||
+ | |||
+ | First set the root password (once), use that to login, and then copy a public ssh key to '' | ||
+ | |||
+ | sshd works with three authorized keys files: | ||
+ | * '' | ||
+ | * '' | ||
+ | * ''/ | ||
+ | |||
+ | The third file contains the keys we use for Remote Support login. | ||
+ | |||
+ | ==== 3.5 Play time! Start executing commands ==== | ||
+ | |||
+ | https:// | ||
+ | |||
+ | ===== 4. Customizing a GX device ===== | ||
+ | |||
+ | ==== 4.1 Hooks to install/run own code at boot ==== | ||
+ | |||
+ | Everything, except for information on ''/ | ||
+ | |||
+ | Therefore, the trick to make changes & modifications survive an update, is to put your (patch)files on ''/ | ||
+ | |||
+ | If the files ''/ | ||
+ | |||
+ | Also if '' | ||
+ | |||
+ | That venus-data file has one extra feature: if the archive contains '' | ||
You can test the ' | You can test the ' | ||
- | / | + | '' |
which will install the same version again, but in the other rootfs. | which will install the same version again, but in the other rootfs. | ||
Line 26: | Line 101: | ||
https:// | https:// | ||
- | ==== Partitions and available disk space ==== | + | ==== 4.2 Partitions, read-only rootfs |
On a GX Device, there are three partitions that matter: | On a GX Device, there are three partitions that matter: | ||
Line 34: | Line 109: | ||
* the data partition | * the data partition | ||
- | Only one of the two rootfs partitions will be in use. When doing a firmware update, | + | === 4.2.1 One active rootfs at a time === |
+ | |||
+ | Only one of the two rootfs partitions will be in use at time. During | ||
The data partition is not touched during a firmware update, except maybe some migration scripts that run at boot. | The data partition is not touched during a firmware update, except maybe some migration scripts that run at boot. | ||
+ | |||
+ | === 4.2.2 Read-only rootfs === | ||
+ | |||
+ | By default, the rootfs is mounted read only. Also, by default, it only has 5% of free space. | ||
+ | |||
+ | The solution is to run ''/ | ||
+ | |||
+ | Further details in the next section. | ||
+ | |||
+ | === 4.2.3 Always prevent running out of diskspace === | ||
When doing modifications, | When doing modifications, | ||
Line 42: | Line 129: | ||
With regards to the size of the data partition, thats easy to check using the '' | With regards to the size of the data partition, thats easy to check using the '' | ||
- | After logging into a GX device, and checking the free disk space on the rootfs(! | + | After logging into a GX device, and checking the free disk space on the rootfs (! that is not the data partition), you might get a bit disappointed at first. Don't worry about that, there will always be only 5% of free space, but thats not the actual free space: |
- | The reason | + | The reason |
- | To see the full space, run ''/ | + | To expand it, run ''/ |
+ | |||
+ | Also this remounts that rootfs as read-write. | ||
For actual available diskspace on our GX Devices, see https:// | For actual available diskspace on our GX Devices, see https:// | ||
- | To see what resize2fs.sh is doing, without having to log into your Venus OS, see it also [[https:// | + | To see what '' |
- | Note that a firmware update will replace all of the rootfs, as also explained above. Which implies that you'll need to run resize2fs.sh again after doing a firmware update. | + | Note that a firmware update will replace all of the rootfs, as also explained above. Which implies that you'll need to run '' |
- | ==== 1. Set access level to Superuser | + | ==== 4.3 Creating a patch file ==== |
- | To set the root password, first set the access level to Superuser: | + | |
- | - Go to Settings, General | + | |
- | - Set the Access Level to User and installer, the password is ZZZ | + | |
- | - Highlight Access Level (don't open the select page!) | + | |
- | - 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. | + | As mentioned before, |
- | ==== 2. Create | + | You start by making a copy of the original file and modifying it to accommodate your changes. In order to create |
- | Go to Settings | + | diff -u OriginalFile UpdatedFile |
- | Note that, for firmware version v2.00 and later, | + | In order to patch the original |
- | 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. | + | patch OriginalFile < PatchFile |
- | ==== 3. Enable sshd and log in ===== | + | For more advanced features please check the manual page of [[https:// |
- | To login via ssh, enable Remote Support (Settings -> General). Besides enabling the reverse tunnel it also enables sshd. More info on Remote Support [[ccgx: | + | ==== 4.4 Adding or modifying services ==== |
- | To the login, enter the ip address of the ccgx in a ssh client. Most Linux and Mac users will simply do this from the command line: | + | Changes made to ''/ |
+ | reason is the ''/ | ||
+ | from ''/ | ||
+ | that under ''/ | ||
+ | to change | ||
+ | ''/ | ||
- | ssh root@192.168.1.23 | + | By default the root filesystem of Venus is read-only. There are three ways to change that: |
- | And a very commonly used client for Windows is [[http://www.chiark.greenend.org.uk/~sgtatham/putty/ | + | * //temporally//: issue the command '' |
+ | * // | ||
+ | * // | ||
- | ==== 4. Working with ssh keys ==== | + | ===== 5. Hardening a GX device ===== |
- | Using a ssh key for authentication, | + | ==== 5.1 Limit physical access to the device ==== |
- | First set the root password (once), use that to login, and then copy a public ssh key to ~/ | + | The first thing to keep in mind is that we as Victron Energy always want an |
+ | end-user with physical access | ||
+ | device again after he has himself accidentally locked out. | ||
- | sshd works with three authorized keys files: | + | So the best solution to keep people from tampering |
- | * ~/.ssh/ | + | is to block physical access to the device. We do not give specific |
- | * ~/.ssh/ | + | recommendations regarding that, but a compact server rack with key protection |
- | * / | + | seems to be safe enough in most cases. You can also add an alarm on the digital |
+ | input of the Cerbo that will ring as soon as the door of the rack opens. | ||
- | The third file contains | + | People with enough time, knowledge and for example an angle grinder on their hands will |
+ | always be able to get in. But you will probably be able to tell if people did | ||
+ | get access to the device. Also keep in mind that extra physical security will | ||
+ | also give extra hassle | ||
+ | access to the device. | ||
- | ==== 5. Play time! Start executing | + | ==== 5.2 Disable touch on the attached screen ==== |
+ | |||
+ | Per Venus OS version v3.00, we are introducing a feature that allows disabling the touch feature on the GX Touch display. | ||
+ | |||
+ | This allows mounting the GX Touch where it is visible by the operators of the system; and at the same time prevent them from using that to elevate their access. | ||
+ | |||
+ | Details per GX device: | ||
+ | * Ekrano GX: a digital input can be configured to be used for this. Wire it to a momentary-push button, that shorts the input (grounds it). | ||
+ | * Cerbo GX + GX touch: a digital input can be configured to be used for this. Wire it to a momentary-push button, that shorts the input (grounds it). | ||
+ | * Venus GX: has no screen, not relevant. | ||
+ | * Color Control GX: will not get this feature. | ||
+ | |||
+ | Inside Venus OS, this is handled by the setting ''/ | ||
+ | |||
+ | Note that this setting only disables touch/mouse control. On the remote console you are still able to control the device with keyboard input. That is also true if you plugin an external USB keyboard. With the keyboard it is also possible to toggle the ''/ | ||
+ | |||
+ | ==== 5.3 Limiting digital access | ||
+ | |||
+ | When securing the device, it is also advised to disable the Wi-Fi access point, | ||
+ | bluetooth and other non-essential services on the device. The below list should | ||
+ | be treated as a starting point and can be extended up on: | ||
+ | |||
+ | * Disable remote touch control | ||
+ | * Disable bluetooth | ||
+ | * Disable Wi-Fi Access point | ||
+ | * Set Access level to User | ||
+ | * Disable LAN SSH | ||
+ | * Disable LAN remote console (VNC) | ||
+ | * Disable Modbus TCP | ||
+ | * Disable MQTT (via SSL, plaintext and VRM) | ||
+ | |||
+ | If you have multiple devices to harden, here is an example of how to automate the process in | ||
+ | a scriptable way. Note that we might change those commands, or names and locations of those settings. Therefore, make sure to be careful to check for example the exit code of such script, as well as visually confirm that all works as expected: | ||
+ | |||
+ | # | ||
+ | |||
+ | items=" | ||
+ | Disable remote touch control; | ||
+ | Disable bluetooth; | ||
+ | Disable Wi-Fi AP; | ||
+ | Set access level to User; | ||
+ | Disable LAN ssh; | ||
+ | Disable LAN Remote console (VNC); | ||
+ | Disable Modbus TCP; | ||
+ | Disable Modbus TCP (Plaintext); | ||
+ | Disable MQTT on LAN (SSL); | ||
+ | Disable MQTT on LAN (Plaintext); | ||
+ | Disable MQTT via VRM; | ||
+ | " | ||
+ | |||
+ | IFS=' | ||
+ | ' | ||
+ | for item in ${items} | ||
+ | do | ||
+ | IFS=';' | ||
+ | echo "# ${description}" | ||
+ | dbus -y ${service} ${path} SetValue ${value} | ||
+ | done | ||
+ | |||
+ | There are //a lot// more settings that can be adjusted this way. Easiest is using | ||
+ | '' | ||
+ | you might want to enable some things too. Just replace the '' | ||
+ | that. | ||
+ | |||
+ | ==== 5.4 Installing a tamper alarm ==== | ||
+ | |||
+ | By using the digital input(s) of the GX device, you can set the digital | ||
+ | inputs as "// | ||
+ | |||
+ | Depending on the need, you might want to switch to a silent alarm under //General -> Audible alarm// | ||
+ | (service: '' | ||
+ | |||
+ | You can decide whether the input should be treated as an alarm condition, | ||
+ | whether the labels should be inverted, and whether the logical levels should be | ||
+ | inverted. | ||
+ | |||
+ | * To swap the labels attached to the alarm, set // | ||
+ | * If a logical low input (0V) should be considered a positive condition, set //Inverted alarm logic// to on. | ||
+ | |||
+ | ==== 5.5 Hardening multiple devices ==== | ||
+ | |||
+ | If you have a lot of Venus devices to modify, probably the easiest way is to | ||
+ | start with using a per-device specific password for the remote console, which | ||
+ | only you can can generate. Combining that with a substring from something like | ||
+ | ''/ | ||
+ | fairly secure start. | ||
+ | |||
+ | Later replace that by something more strong and store it in your vault. Use the USB stick to put your public ssh keys on the GX device so you can gain remote access. | ||
+ | |||
+ | ===== 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: https:// | ||
+ | |||
+ | The serial consoles on all GX devices are configured to 115200 baud. | ||
+ | |||
+ | ==== 6.1 Color Control GX ==== | ||
+ | |||
+ | All GX Devices have a dedicated serial console, except for the CCGX. Therefor its documented on a separate page: | ||
+ | |||
+ | [[https:// | ||
+ | |||
+ | ==== 6.2 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 [[https:// | ||
+ | |||
+ | Make sure not to connect the red wire. | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | ==== 6.3 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: | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | ==== 6.4 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/ | ||
+ | |||
+ | 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. | ||
+ | |||
+ | {{ : | ||
- | https:// | ||
- | ==== 6. Connecting via the console instead of over ssh ==== | + | ==== 6.5 Octo GX ==== |
- | First, note that this is only relevant for the CCGX, as the Beagleboards have a uart dedicated to a console | + | The serial console |
- | See menu item Settings | + | |
+ | | ||
+ | - NC | ||
+ | - Green: RX of the Beaglecore - connect to TX on your cable | ||
+ | - White: TX of the Beaglecore - connect to RX on your cable | ||
+ | - NC | ||
- | Enable | + | Make sure not to connect |
- | Settings are 115k2 / 8N1. Note that a normal VE.Direct to USB interface cable won't work, since you need to power the VE.Direct port on the CCGX from the outside. A small mod can be made to the interface cable. [[https:// | + | {{ :ccgx:octo-gx_serial-console.jpg? |
+ | ==== 6.6 Ekrano GX ==== | ||
+ | Getting to console on the Ekrano GX is not that easy. The pins are located between the network and USB connector on the back of the device. | ||
- | ===== DISQUS ===== | + | - Black: ground |
- | ~~DISQUS~~ | + | - NC |
+ | - NC | ||
+ | - Green: RX of the Ekrano GX - connect to TX on your cable | ||
+ | - White: TX of the Ekrano GX - connect to RX on your cable | ||
+ | - NC | ||
+ | {{ : |
ccgx/root_access.txt · Last modified: 2024-02-09 17:06 by dfaber