Software manual - BITMOTECO Platform
Version 2.1.1 | EN | 08-2024
Coming soon
The complete document is currently only available in German: See here
Shell login
The average user of the BITMOTECOsystem does not need to use the internal shell from the command line interface.
The provided web-based GUI module provides an interface for basic system administration and module management.
However, the use of the internal shell is and will always be possible.
If you are reading this for the first time, it is very likely that you will need the unique support password for your BITMOTECOsystem from our support.
In order to log in to the system shell of any BITMOTECOsystem, it is necessary to select a user to log in as.
The following users are available:
| username | login with password | login with ssh-key | permissions |
|---|---|---|---|
| info | y | n | very limited |
| user | y | n | limited |
| support | y | y | all (with sudo) |
| root | n | y | all |
The info and user users are intended for customer use and not for technical support.
Preferred order of ways to login:
- Login over SSH as
rootuser with own private key - Login over SSH as
supportuser with password - Local login as
supportuser with password
If your own SSH key is authorised for a particular user to log in with, you can continue with your own SSH key.
If you do not have access to an authorised key, you will need to add your private key via the SSH key management.
If you do not have a private SSH key, start with creating one.
Start SSH server
If the SSH server on the BITMOTECOsystem is not running you need to start it. It is disabled by default.
Instructions on how to start the SH server can be found here
Login with private SSH key
As long as a SSH server is running on the target and your private key is authorized for the chosen user, you are good to go.
Run following command to login:
$> ssh root@<NodeIP/NodeDNSName>
If the support access was enabled by starting a SSH server on a different port (like 1234) use:
$> ssh -p 1234 root@<NodeIP/NodeDNSName>
Get access without private key
If you do not have shell access to the system, you will need to create your own SSH key pair and add the public part to the system in order to gain shell access.
Create a private SSH key
Generate a new SSH key on your local machine.
This creates a new SSH key, using an email as a label:
$> ssh-keygen -t ed25519 -C "your_email@example.com"
Give the key a reasonable passphrase to protect it from unauthorized use.
However, one must never loose or share the private part of the generated key!
It is recommended to store the newly created key pair under ~/.ssh/bitmoteco/<nodeId>/
Setup SSH config
Optional
Linux SSH client configuration examples for automatic private identity file selection for given hosts and subnets.
Belongs into ~/.ssh/config
...
### BITMTOECO System <nodeId>
Host <IP OR DNS NAME (like 192.168.1.2)>
AddKeysToAgent yes
IdentityFile ~/.ssh/bitmoteco/<nodeId>/<privateKeyFile>
...
Add key with an other authorized private SSH key
If your private SSH key is not pre-authorized, you need to add it to the list of authorized keys for the chosen user.
Use an authorized private key to login as root:
$> ssh -i ~/.ssh/bitmoteco/<nodeId>/ root@<NodeIP/NodeDNSName>
Add the newly generated key to the authorized keys lists and logout again:
$> nano /root/.ssh/authorized_keys
$> nano /home/support/.ssh/authorized_keys
$> exit
You can now log in via SSH using your own SSH key.
Add key with the support password
Once you have received the unique support password, you can use it to log in as the support user via SSH or locally using a display and keyboard.
Add the newly generated key to the authorized keys lists and logout again:
$> nano /home/support/.ssh/authorized_keys
$> sudo nano /root/.ssh/authorized_keys
$> exit
You can now log in via SSH using your own SSH key.
Manage SSH keys
With shell
Authorized SSH keys are stored in a special file per user in their home directory under ~/.ssh/authorized_keys.
This file can be edited with a text editor to add or remove keys.
* To remove a key, simply delete the corresponding line
* To add a key, add a line containing the public part of an SSH key (contents of key.pub) with the key type, the public part of the key and the comment separated by a space.
Example line:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILovgzVpHhg0abcQKLqWOqlzuB2TDWpJLPJ1v35CoZ8F user@example.com
Edit the key lists:
$> nano /home/support/.ssh/authorized_keys
$> nano /root/.ssh/authorized_keys
Get the unique support password
Each BITMOTECOsystem has a unique support password which is generated and set by default for the user support.
This password can be requested from the Bitmotec support team.
To retrieve the password, the unique BITMOTECOsystem ID32 is required.
It is displayed in the GUI and TUI.
Once you have received the password from our support, you can use it to log in as the support user via SSH or locally using a display and keyboard.
Terminal User Interface (TUI)
This interface can be used locally to show some device information and configure basic system settings. When using a physical instead of a virtual device it is necessary to connect a monitor and keyboard in order to access this interface. When SSH is enabled it can also be accessed remotely.
All submenus are selected by pressing the corresponding number and the ENTER key afterwards.
Menu for the info user
A simple local information menu which can be accessed by the user.
It can be used to get the network addresses of all interfaces, show all opened network ports or give some basic device information.
Main menu
Current user: info
+--------------------< MENU >--------------------+
| |
| 1) Show network settings (Return with 'q') |
| |
| 2) Show unix user information |
| |
| 3) Show open ports on this system |
| |
| 4) Show device info |
| |
| 0) Exit |
| |
+------------------------------------------------+
Please select a menu item:
Show network settings
Show the network address configuration and current state for all non-internal network interfaces. One can leave this view by pressing Q on the keyboard.
This is an example output!
2: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
link/ether xx:xx:xx:xx:xx:xx brd ff:ff:ff:ff:ff:ff
inet 10.1.1.1/24 brd 10.1.1.255 scope global enp1s0
valid_lft forever preferred_lft forever
inet6 fe80::xxxx:xxxx:fe12:xxxx/64 scope link
valid_lft forever preferred_lft forever
3: enp2s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
link/ether xx:xx:xx:xx:xx:xx brd ff:ff:ff:ff:ff:ff
inet 192.168.1.2/24 metric 100 brd 192.168.30.255 scope global dynamic enp2s0
valid_lft 110103sec preferred_lft 110103sec
inet6 fe80::xxxx:xxxx:fe12:xxxx/64 scope link
valid_lft forever preferred_lft forever
(END)
Show unix user information
Show the current user name and groups.
The output and should always look like this:
Current user: info
Main group: info
Additional groups: info
Show open ports on this system
List of open ports and bound addresses and interfaces for incoming connections for the UDP/IP and TCP/IP protocol.
This is an example output!
Netid State Recv-Q Send-Q Local Address:Port Peer Address:Port Process
udp UNCONN 0 0 127.0.0.53%lo:53 0.0.0.0:*
udp UNCONN 0 0 192.168.30.172%enp2s0:68 0.0.0.0:*
udp UNCONN 0 0 127.0.0.1:323 0.0.0.0:*
udp UNCONN 0 0 [::1]:323 [::]:*
tcp LISTEN 0 128 0.0.0.0:22 0.0.0.0:*
tcp LISTEN 0 4096 0.0.0.0:80 0.0.0.0:*
tcp LISTEN 0 4096 0.0.0.0:443 0.0.0.0:*
tcp LISTEN 0 100 172.16.1.1:4100 0.0.0.0:*
tcp LISTEN 0 100 172.16.1.1:4200 0.0.0.0:*
tcp LISTEN 0 511 127.0.0.1:22350 0.0.0.0:*
tcp LISTEN 0 4096 127.0.0.1:35111 0.0.0.0:*
tcp LISTEN 0 4096 127.0.0.53%lo:53 0.0.0.0:*
tcp LISTEN 0 100 172.16.1.1:4000 0.0.0.0:*
tcp LISTEN 0 100 127.0.0.1:4200 0.0.0.0:*
tcp LISTEN 0 100 127.0.0.1:4100 0.0.0.0:*
tcp LISTEN 0 128 [::]:22 [::]:*
tcp LISTEN 0 4096 [::]:80 [::]:*
tcp LISTEN 0 4096 [::]:443 [::]:*
Show device info (System ID)
Shows the current version of the BITMOTECOsystem, the hexadecimal identifier (System ID) and the unique hexadecimal ID (System ID 32).
Name: BITMOTECO Core OS
Version: x.x.x
System ID : xxxxxx
System ID 32: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Menu for the user user
A local configuration menu which can be accessed by the user user.
Its primary use is to setup the network interfaces in a way that the web-based user interface is accessible from an other device.
Furthermore it can be used to start the SSH service.
Main menu
Current user: user
+--------------< MAIN MENU >---------------------+
| |
| 1) Network settings |
| |
| 2) User settings |
| |
| 3) Application settings |
| |
| 4) Support |
| |
| 5) Show device info |
| |
| 6) Shutdown / Reboot |
| |
| 0) Exit |
| |
+------------------------------------------------+
Please select a menu item:
Network settings
Show and change the network settings of the device.
+--------------< NETWORK MENU >------------------+
| |
| 1) Show network settings (Return with 'q') |
| |
| 2) Edit network settings |
| |
| 3) Toggle WiFi access point |
| |
| 4) Set NTP server |
| |
| 5) Set HTTP/HTTPS proxy |
| |
| 6) Show open ports on this system |
| |
| 0) Return |
| |
+------------------------------------------------+
Please select a menu item:
Show network settings
See menu for
infouser
Edit network settings
Select which interface to configure: * 02-bmt-main.yaml: Used for main interface which uses DHCP by default * 03-bmt-add.yaml: Used for all further interfaces which by default are configured with a static IP like 10.1.X.1/24 where X is a counter starting by 1 for the first additional interface * 04-bmt-wifi.yaml: Used for the WiFi interface which, if available, is configured by default to use the static IP 10.10.1.1/24
+--------------< NETPLAN MENU >------------------+
| |
| 1) /etc/netplan/02-bmt-main.yaml
| |
| 2) /etc/netplan/03-bmt-add.yaml
| |
| 3) /etc/netplan/04-bmt-wifi.yaml
| |
| |
| 0) Return |
| |
+------------------------------------------------+
Please select a file:
After selection one file by entering the corresponding number and pressing the ENTER key an editor opens which allows to edit the content of the file.
The network interfaces are configured by Canonicals Netplan utility and thus a valid Format is required.
Here are some examples for common configurations: Example configurations
The edited file can be saved by pressing CTRL+O and afterwards the editor can be closed by pressing CTRL+X.
This is an example output!
network:
version: 2
renderer: networkd
ethernets:
enp1s0:
optional: true
dhcp4: false
dhcp6: false
addresses:
- 10.1.1.1/24
^G Help ^O Write Out ^W Where Is ^K Cut ^T Execute ^C Location M-U Undo
^X Exit ^R Read File ^\ Replace ^U Paste ^J Justify ^/ Go To Line M-E Redo
To apply the new configuration simply press ENTER after the following prompt:
= New network configuration =
In order to force this configuration please insert 'Force' before pressing ENTER.
For normal edits please only press ENTER to try this settings:
The system will then check and try the new network settings but revert them if they are not approved by the user within 30 seconds. This is a lock-out protection when changing network settings remotely.
A second press of the ENTER key approves the settings and finally ends the configuration process.
Do you want to keep these settings?
Press ENTER before the timeout to accept the new configuration
Changes will revert in 30 seconds
Toggle WiFi access point
Toggles the state of the local WiFi Access Point which can be used to setup the device. It is only available when a capable network interface was found and disabled by default.
Please disable it for security reasons if you don't need it anymore!
Current WiFi AP state: enabled
Type 'yes' and press enter to disable the internal WiFi access point:
Set NTP server
Set the NTP (Network Time Protocol) server to be used for clock synchronising. Defaults to "ntp.ubuntu.com".
This is an example output!
Please type 'Yes' to set a custom NTP server.
Enable custom NTP server? yes
Please enter NTP server address: 192.168.1.10
Set HTTP/HTTPS proxy
Set the system-wide proxy for HTTP (Hypertext Transfer Protocol) and HTTPS (Hypertext Transfer Protocol Secure) requests.
This is an example output!
Please type 'Yes' to set a proxy server.
Enable custom proxy server? yes
Please enter proxy server IP address: 192.168.1.26
Show open ports on this system
See menu for
infouser
User settings
+--------------< USER MENU >---------------------+
| |
| 1) Show unix user information |
| |
| 2) Change password |
| |
| 0) Return |
| |
+------------------------------------------------+
Please select a menu item:
Show unix user information
See menu for
infouser
Change password
Set a new password for the user user.
Application settings
Application specific settings currently only used to configure the Mosquitto MQTT broker module if it is installed.
+--------------< APPLICATION MENU >--------------+
| |
| 1) Edit MQTT Broker configuration |
| |
| 2) Edit MQTT Broker users |
| |
| 0) Return |
| |
+------------------------------------------------+
Please select a menu item:
After selection one file by entering the corresponding number and pressing the ENTER key an editor opens which allows to edit the content of the file.
The edited file can be saved by pressing CTRL+O and afterwards the editor can be closed by pressing CTRL+X.
Edit MQTT Broker configuration
After changing the broker configuration it must be applied by restarting the Mosquitto MQTT broker module via the web interface.
Edit MQTT Broker users
After changing the user authentication configuration the changes must be applied by restarting the Mosquitto MQTT broker module via the web interface.
Support (SSH server)
Start the SSH server and toggle its autostart.
+--------------< SUPPORT MENU >------------------+
| |
| 1) Start SSH server |
| |
| 2) Toggle SSH server by default |
| |
| 0) Return |
| |
+------------------------------------------------+
Please select a menu item:
Start SSH server
Start the SSH server once. Is is not reactivated after a reboot or crash.
When the SSH server gets started the output should look like this:
● ssh.service - OpenBSD Secure Shell server
Loaded: loaded (/lib/systemd/system/ssh.service; enabled; vendor preset: enabled)
Drop-In: /etc/systemd/system/ssh.service.d
└─ssh.auto_enable.conf
Active: active (running) since [...]
Docs: man:sshd(8)
man:sshd_config(5)
Process: 2802 ExecStartPre=/usr/sbin/sshd -t (code=exited, status=0/SUCCESS)
Main PID: 2803
Tasks: 1 (limit: 4402)
Memory: 1.7M
CPU: 42ms
CGroup: /system.slice/ssh.service
└─2803 "sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups"
Toggle SSH server by default
Change wether the SSH service should automatically be started after the system has booted and be restarted after a crash.
Current SSH service state: disabled
Type 'yes' and press enter to enable the SSH server by default:
Show device info (System ID)
See menu for
infouser
Power menu (shutdown / reboot)
Power off or restart the system.
+--------------< POWER MENU >--------------------+
| |
| 1) Power off the system |
| |
| 2) Reboot the system |
| |
| 0) Return |
| |
+------------------------------------------------+
Please select a menu item: