Victron Energy

User Tools

Site Tools

You are here: Documentation » ccgx » Venus OS: Root Access
ccgx:root_access

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
ccgx:root_access [2023-02-01 22:57] – [Hooks to install/run own code at boot] mvaderccgx:root_access [2024-02-09 17:06] (current) – [4.1 Hooks to install/run own code at boot] dfaber
Line 1: Line 1:
 ====== Venus OS: Root Access ====== ====== Venus OS: Root Access ======
  
-===== Introduction =====+===== 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.+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://github.com/victronenergy/venus/wiki|the Venus OS wiki on github]]. This document is part of the Venus OS developer documentation. The main document is [[https://github.com/victronenergy/venus/wiki|the Venus OS wiki on github]].
Line 9: Line 9:
 Do note that, while we try to maintain to provide all mentioned functionality in this document, the used commands and functionality may change with future updates. Do note that, while we try to maintain to provide all mentioned functionality in this document, the used commands and functionality may change with future updates.
  
-===== Warning about modifying the rootfs =====+===== 2. Warning about modifying the rootfs =====
  
 __1. Your changes can be lost during a firmware update__ __1. Your changes can be lost during a firmware update__
Line 30: Line 30:
   - if you remove the files in /data/venus, then -depending on the production date- you might have to restore those manually which might require serial console access. See below. Why does this depend on the production date? Thats because somewhere in 2021 we started writing all factory data to a different place (an eeprom) to make it more robust.   - if you remove the files in /data/venus, then -depending on the production date- you might have to restore those manually which might require serial console access. See below. Why does this depend on the production date? Thats because somewhere in 2021 we started writing all factory data to a different place (an eeprom) to make it more robust.
  
-======= Root access ======+===== 3. Root access =====
  
-==== Set access level to Superuser ====+==== 3.1 Set access level to Superuser ====
 To set the root password, first set the access level to Superuser: To set the root password, first set the access level to Superuser:
   - Go to Settings, General   - Go to Settings, General
Line 43: Line 43:
 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. 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.
  
-==== Create a temporary root password ====+==== 3.2 Create a temporary root password ====
  
 Go to //Settings -> General -> Set root password//. And create a temporary root password. Go to //Settings -> General -> Set root password//. And create a temporary root password.
Line 49: Line 49:
 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://github.com/victronenergy/venus/wiki/swupdate-project|here]]. 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://github.com/victronenergy/venus/wiki/swupdate-project|here]].
  
-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 also +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 delete the root password afterwards (''passwd --delete root'').+safely disallow root logins with a password with '' echo 'root:*' | chpasswd -e ''.
  
-==== Enable sshd and log in =====+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 [[ccgx:ccgx_faq#what_is_the_functionality_behind_the_menu_item_remote_support_ssh_in_the_ethernet_menu|here]].+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://www.victronenergy.com/media/pg/Cerbo_GX/en/troubleshooting.html#UUID-f13193f4-c359-4a49-005e-05da0fdd6a70|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: 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:
Line 62: Line 63:
 And a very commonly used client for Windows is [[http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html|Putty]]. For more info, look around on the Internet, there is [[https://www.google.nl/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=putty+ssh+login&tbm=vid|plenty information]] available. And a very commonly used client for Windows is [[http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html|Putty]]. For more info, look around on the Internet, there is [[https://www.google.nl/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=putty+ssh+login&tbm=vid|plenty information]] available.
  
-==== Installing ssh keys ====+==== 3.4 Installing 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. 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.
Line 75: Line 76:
 The third file contains the keys we use for Remote Support login. The third file contains the keys we use for Remote Support login.
  
-==== Play time! Start executing commands ====+==== 3.5 Play time! Start executing commands ====
  
 https://www.victronenergy.com/live/open_source:ccgx:commandline https://www.victronenergy.com/live/open_source:ccgx:commandline
  
-======= Customizing a Venus GX device =======+===== 4. Customizing a GX device =====
  
-Our recommended method to customize Venus OS is by making ''.patch'' files, storing them on the data partition, and applying at boot using either the ''/data/rcS.local'' or the ''/data/rc.local'' script. +==== 4.1 Hooks to install/run own code at boot ====
- +
-==== Hooks to install/run own code at boot ====+
  
 Everything, except for information on ''/data'', will be wiped after an update. Everything, except for information on ''/data'', will be wiped after an update.
  
-Therefore, the trick to make changes & modifications survive an update, is to put your (patch)files on ''/data'', make them be (re-)installed automatically on startup. This section describes how to do that.+Therefore, the trick to make changes & modifications survive an update, is to put your (patch)files on ''/data'', make them be (re-)installed automatically on startup. 
  
 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 [[https://github.com/victronenergy/meta-victronenergy/commit/2dbd16c560ff7cdf70b1d676c0616013169c7484|this commit]]. 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 [[https://github.com/victronenergy/meta-victronenergy/commit/2dbd16c560ff7cdf70b1d676c0616013169c7484|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 [[https://github.com/victronenergy/meta-victronenergy/commit/469760fef4ed2ee977f482c997ac24c2678222c5|this commit]]. Added per Venus v2.30~28. Use this to for example make a USB stick that installs the modifications. +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 [[https://github.com/victronenergy/meta-victronenergy/commit/469760fef4ed2ee977f482c997ac24c2678222c5|this commit]]. Added per Venus v2.30~28. Use this to for example make a USB stick that installs the modifications. You can combine multiple files on the device; they will be run in alphabetical order.
- +
-That venus-data file has one extra feature: if the archive contains ''rc/*'' files, it will extract those first. And if there is a file called ''rc/pre-hook.sh'' it will run this before unpacking the rest of the archive. +
- +
-Similarly, if there is a file called ''rc/post-hook.sh'', then that file will run this after the unpacking of the +
-archive.+
  
-For details, read the code in the ''/etc/rc5.d/S30update-data.sh'' file.+That venus-data file has one extra feature: if the archive contains ''rc/*'' files, it will extract those first. And if there is a file called ''rc/pre-hook.sh'' it will run this before unpacking the rest of the archive. Similarly, if there is a file called ''rc/post-hook.sh'', then that file will run this after the unpacking of the archive. For details, read the code in the ''/etc/rc5.d/S30update-data.sh'' file.
  
-The advice is to put unified patches in the ''venus-data.tgz'' archive that +You can draw further inspiration from [[https://github.com/victronenergy/meta-victronenergy/tree/master/meta-venus/scripts|here]], where the code resides to generate files for making backups of the ''/data'' partition, resetting Node-RED and SignalK and more scripts. 
-holds patches against the services in ''/opt/victronenergy/services/'' that you +
-want to patch.+
  
 You can test the 'update' with  You can test the 'update' with 
Line 111: Line 103:
 https://github.com/victronenergy/venus/wiki/swupdate-project https://github.com/victronenergy/venus/wiki/swupdate-project
  
-==== Partitions, read-only rootfs and available disk space ====+==== 4.2 Partitions, read-only rootfs and available disk space ====
  
 On a GX Device, there are three partitions that matter: On a GX Device, there are three partitions that matter:
Line 119: Line 111:
   * the data partition   * the data partition
  
-=== One active rootfs at a time ===+=== 4.2.1 One active rootfs at a time ===
  
 Only one of the two rootfs partitions will be in use at time. During a firmware update, the new firmware is installed on the other one; and once finished the subsequent reboot will reboot the device onto that other partition. Only one of the two rootfs partitions will be in use at time. During a firmware update, the new firmware is installed on the other one; and once finished the subsequent reboot will reboot the device onto that other partition.
Line 125: Line 117:
 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.
  
-=== Always prevent running out of diskspace ===+=== 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 ''/opt/victronenergy/swupdate-scripts/resize2fs.sh''. 
 + 
 +Further details in the next section. 
 + 
 +=== 4.2.3 Always prevent running out of diskspace ===
  
 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. 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.
Line 131: Line 131:
 With regards to the size of the data partition, thats easy to check using the ''df'' utility. But not so for the rootfs: 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 about that, there will always be only 5% of free space, but thats not the actual free space:+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 for this 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.+The reason for this is that a firmware update replaces the full filesystem on the rootfs, as an image. And its then **not** by default expanded to the full available space of the partition.
  
 To expand it, run ''/opt/victronenergy/swupdate-scripts/resize2fs.sh''. It will expand the filesystem to use all of the available space. To expand it, run ''/opt/victronenergy/swupdate-scripts/resize2fs.sh''. It will expand the filesystem to use all of the available space.
Line 145: Line 145:
 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 ''resize2fs.sh'' again after doing a firmware update.
  
-===== Adding or modifying services =====+==== 4.3 Creating a patch file ==== 
 + 
 +As mentioned before, the recommended way of customising Venus OS is by applying patch files. This section describes how to make and apply a patch. 
 + 
 +You start by making a copy of the original file and modifying it to accommodate your changes. In order to create a patch file containing the changes you’ve made, run the following command: 
 + 
 +    diff -u OriginalFile UpdatedFile > PatchFile 
 + 
 +In order to patch the original file with your changes, you can use the below command: 
 + 
 +    patch OriginalFile < PatchFile 
 + 
 +For more advanced features please check the manual page of [[https://man7.org/linux/man-pages/man1/diff.1.html|diff]] and [[https://man7.org/linux/man-pages/man1/patch.1.html|patch]]. 
 + 
 +==== 4.4 Adding or modifying services ====
  
 Changes made to ''/service'' will not survive a reboot. The Changes made to ''/service'' will not survive a reboot. The
Line 160: Line 174:
   * //permanent//: adding one of the above commands to ''/data/rc.local'' (which holds permanently)   * //permanent//: adding one of the above commands to ''/data/rc.local'' (which holds permanently)
  
-======= Hardening a Venus GX device =======+===== 5. Hardening a GX device =====
  
-===== Limit physical access to the device =====+==== 5.1 Limit physical access to the device ====
  
 The first thing to keep in mind is that we as Victron Energy always want an The first thing to keep in mind is that we as Victron Energy always want an
Line 180: Line 194:
 access to the device. access to the device.
  
-===== Disable touch on the attached screen =====+==== 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. Per Venus OS version v3.00, we are introducing a feature that allows disabling the touch feature on the GX Touch display.
Line 187: Line 201:
  
 Details per GX device: 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).   * 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.   * Venus GX: has no screen, not relevant.
   * Color Control GX: will not get this feature.   * Color Control GX: will not get this feature.
  
-Inside Venus OS, this is handled by the setting ''/Settings/Gui/TouchEnabled''. And that can be used to, for example, disable touch on each boot by using the boot scripts and dbus -y command. +Inside Venus OS, this is handled by the setting ''/Settings/Gui/TouchEnabled'' under ''com.victronenergy.settings''. Which can be scripted with the ''dbus -y'' command. See [[#limiting_digital_access|Limiting digital access]] for an example on how to do that. 
-===== Limiting digital access  =====+ 
 +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 ''/Settings/Gui/TouchEnabled'' setting by pressing the [[https://en.wikipedia.org/wiki/Break_key|Pause/Break key]] key. So if you need this feature to be switched on, make sure that the USB ports are not accessible. 
 + 
 +==== 5.3 Limiting digital access  ====
  
 When securing the device, it is also advised to disable the Wi-Fi access point, When securing the device, it is also advised to disable the Wi-Fi access point,
Line 205: Line 222:
   * Disable LAN SSH   * Disable LAN SSH
   * Disable LAN remote console (VNC)   * 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 If you have multiple devices to harden, here is an example of how to automate the process in
Line 218: Line 237:
     Disable LAN ssh;com.victronenergy.settings;/Settings/System/SSHLocal;0     Disable LAN ssh;com.victronenergy.settings;/Settings/System/SSHLocal;0
     Disable LAN Remote console (VNC);com.victronenergy.settings;/Settings/System/VncLocal;0     Disable LAN Remote console (VNC);com.victronenergy.settings;/Settings/System/VncLocal;0
 +    Disable Modbus TCP;Settings/Services/Modbus;0
 +    Disable Modbus TCP (Plaintext);Settings/Services/MqttLocalInsecure;0
 +    Disable MQTT on LAN (SSL);Settings/Services/MqttLocal;0
 +    Disable MQTT on LAN (Plaintext);Settings/Services/MqttLocalInsecure;0
 +    Disable MQTT via VRM;Settings/Services/MqttVrm;0
     "     "
          
Line 234: Line 258:
 that. that.
  
-===== Installing a tamper alarm =====+==== 5.4 Installing a tamper alarm ====
  
 By using the digital input(s) of the GX device, you can set the digital By using the digital input(s) of the GX device, you can set the digital
Line 249: Line 273:
   * If a logical low input (0V) should be considered a positive condition, set //Inverted alarm logic// to on.   * If a logical low input (0V) should be considered a positive condition, set //Inverted alarm logic// to on.
  
-===== Hardening multiple devices =====+==== 5.5 Hardening multiple devices ====
  
 If you have a lot of Venus devices to modify, probably the easiest way is to If you have a lot of Venus devices to modify, probably the easiest way is to
Line 259: Line 283:
 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. 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.
  
-======  Connecting on the serial console ======+===== 6. Connecting on the serial console =====
  
 The serial console offers a straight connection from your computer. Not relying on TCP or anything else. The serial console offers a straight connection from your computer. Not relying on TCP or anything else.
Line 269: Line 293:
 The serial consoles on all GX devices are configured to 115200 baud. The serial consoles on all GX devices are configured to 115200 baud.
  
-===== Serial console on GX device =====+==== 6.1 Color Control GX ====
  
 All GX Devices have a dedicated serial console, except for the CCGX. Therefor its documented on a separate page: All GX Devices have a dedicated serial console, except for the CCGX. Therefor its documented on a separate page:
Line 275: Line 299:
 [[https://github.com/victronenergy/venus/wiki/ccgx-serial-console|CCGX Serial Console]]. [[https://github.com/victronenergy/venus/wiki/ccgx-serial-console|CCGX Serial Console]].
  
-===== Serial Console on Cerbo GX =====+==== 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://www.adafruit.com/product/954|ADA Fruit Serial Console cable]] connected to it. 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://www.adafruit.com/product/954|ADA Fruit Serial Console cable]] connected to it.
Line 283: Line 307:
 {{ :ccgx:cerbo_serial_console.jpg?nolink&600 |}} {{ :ccgx:cerbo_serial_console.jpg?nolink&600 |}}
  
-===== Serial Console on Venus GX =====+==== 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. 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.
Line 297: Line 321:
 {{ :ccgx:venus_gx_serial_console.png?nolink&600 |}} {{ :ccgx:venus_gx_serial_console.png?nolink&600 |}}
  
-===== Serial console on GX Card / Nanopi =====+==== 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/chargers. 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.
Line 308: Line 332:
  
  
-===== Serial console on Octo GX =====+==== 6.5 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. 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.
Line 322: Line 346:
  
 {{ :ccgx:octo-gx_serial-console.jpg?300 |}} {{ :ccgx:octo-gx_serial-console.jpg?300 |}}
 +
 +==== 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.
 +
 +  - Black: ground 
 +  - 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:ekrano-console.jpg?300 |}}
ccgx/root_access.1675288659.txt.gz · Last modified: 2023-02-01 22:57 by mvader
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki