From d6c13dbff258b6699bb6d608bd35b684d1b6f4d7 Mon Sep 17 00:00:00 2001 From: Davide Lasagna Date: Thu, 2 Jan 2025 10:22:53 +0100 Subject: [PATCH] added 22.04 page and ansible playbook guide (#381) Co-authored-by: icub --- .../installation-from-ansible-playbook.md | 40 +++++++ .../icubos/installation-from-scratch-22.04.md | 103 +++++++++++++++++ .../other-machines/generic-machine-22.04.md | 106 ++++++++++++++++++ mkdocs.yml | 3 + 4 files changed, 252 insertions(+) create mode 100644 docs/icub_operating_systems/icubos/installation-from-ansible-playbook.md create mode 100644 docs/icub_operating_systems/icubos/installation-from-scratch-22.04.md create mode 100644 docs/icub_operating_systems/other-machines/generic-machine-22.04.md diff --git a/docs/icub_operating_systems/icubos/installation-from-ansible-playbook.md b/docs/icub_operating_systems/icubos/installation-from-ansible-playbook.md new file mode 100644 index 000000000..33cdb8008 --- /dev/null +++ b/docs/icub_operating_systems/icubos/installation-from-ansible-playbook.md @@ -0,0 +1,40 @@ +## Create the USB installer + +The first step is to download the **official Ubuntu 22.04 LTS Server install media** from the [release page](https://releases.ubuntu.com/jammy). Search for `ubuntu-22.04.x-live-server-amd64.iso`. + +Then, please create the USB installer using a USB memory and a tool like [Balena Etcher](https://www.balena.io/etcher/). + +Find further information about creating a bootable USB stick on [Windows](https://ubuntu.com/tutorials/create-a-usb-stick-on-windows#1-overview), [Ubuntu](https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu#1-overview) or [macOS](https://support.apple.com/en-us/101578). + +## Install Ubuntu + +Follow the below steps to install the Ubuntu server on icub-head. + +Please, note that the installation procedure can be slightly different in each release, you can see the [Ubuntu server official install guide](https://ubuntu.com/tutorials/tutorial-install-ubuntu-server) + +!!! warning + + The installation procedure will overwrite the disk of your icub-head, so all data will be deleted. + +## Launch the playbook + +Once the basic OS has been installed it is time to download and launch our playbook: + +The Playbook covers the steps decribed in [iCubOS installation from scratch](https://icub-tech-iit.github.io/documentation/icub_operating_systems/icubos/installation-from-scratch/), [iCub user enviroment](https://icub-tech-iit.github.io/documentation/icub_operating_systems/icubos/user-env/) and [further tasks](https://icub-tech-iit.github.io/documentation/icub_operating_systems/icubos/further-tasks/). + +How to run: + +- clone the repository +- Check the README file for further instructions +- launch as `sudo` the `start.sh` file +``` +git clone https://github.com/icub-tech-iit/iCubOS-playbook.git + +cd iCubOS-playbook/ + +sudo ./start.sh + +``` +A reboot is recommended in order to load the Lowlatency kernel instead of the Generic. + +Once the installation is completed follow the [Networking](https://icub-tech-iit.github.io/documentation/icub_operating_systems/icubos/networking/#external-network-configurations) chapter of the guide to configure the network using netplan or your favourite network manager system. \ No newline at end of file diff --git a/docs/icub_operating_systems/icubos/installation-from-scratch-22.04.md b/docs/icub_operating_systems/icubos/installation-from-scratch-22.04.md new file mode 100644 index 000000000..4b1257171 --- /dev/null +++ b/docs/icub_operating_systems/icubos/installation-from-scratch-22.04.md @@ -0,0 +1,103 @@ +# The OS on icub-head - Installation from scratch + +Since iCubOS is based on the Ubuntu server, we will install the latter from the default installer and then manually customize it. + +## Latest versions + +The latest version is based on Ubuntu Server 22.04 + +## Create the USB installer + +The first step is to download the **official Ubuntu 22.04 LTS Server install media** from the [release page](https://releases.ubuntu.com/jammy). Search for `ubuntu-22.04.x-live-server-amd64.iso`. + +Then, please create the USB installer using a USB memory and a tool like [Balena Etcher](https://www.balena.io/etcher/). + +Find further information about creating a bootable USB stick on [Windows](https://ubuntu.com/tutorials/create-a-usb-stick-on-windows#1-overview), [Ubuntu](https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu#1-overview) or [macOS](https://support.apple.com/en-us/101578). + +## Install Ubuntu + +Follow the below steps to install the Ubuntu server on icub-head. + +Please, note that the installation procedure can be slightly different in each release, you can see the [Ubuntu server official install guide](https://ubuntu.com/tutorials/tutorial-install-ubuntu-server) + +!!! warning + + The installation procedure will overwrite the disk of your icub-head, so all data will be deleted. + +### Ubuntu Installer configuration + +Install the system by choosing the default options, except for the following steps: + +#### Keyboard and language + +- **Layout** : `US` +- **Variant** : `US` + +#### Storage configuration + +- _**Disable** the following option_ : `Setup this disk as an LVM group` + +#### Identity + +- **Your name** : `icub` +- **Your Server's name** : `icub-head` +- **Pick a username** : `icub` +- **Choose a password** : `icub` + +#### SSH + +- _**Enable** the following option_ : `Install SSH server` + +## Required Packages + +Install the following packages +``` +nfs-common python-tk libopencv-dev ntpdate vim ssh cmake-curses-gui iperf libportaudio2 portaudio19-dev linux-sound-base alsa-base alsa-utils gdb meld bmon libi2c-dev expect libgfortran-10-dev qml-module-qt-labs-folderlistmodel qml-module-qt-labs-settings +``` + +### Low Latency kernel + +Install the following packages +``` +linux-image-lowlatency linux-headers-lowlatency +``` + +### Disable X server at startup + +The x server is started automatically at startup by GDM, so please disable GDM +``` +sudo systemctl disable gdm +``` + +## Configuration steps + +### SSH configuration + +1. Configure passwordless ssh: see this [link](https://askubuntu.com/questions/46930/how-can-i-set-up-password-less-ssh-login) +2. Disable reverse DNS lookup in SSH server: add the following line to the file `/etc/ssh/sshd_config` + ``` + UseDNS no + ``` + +### Network performances tweaks + +1. Install the following packages + ``` + sudo apt install linux-image-lowlatency linux-headers-lowlatency + ``` + +2. Modify the real-time priority of the process, add the file `/etc/security/limits.d/icub.conf ` as follows + ``` + icub soft rtprio 99 + icub hard rtprio 99 + ``` + +3. Set the max OS receive-buffer size for all types of connections, by adding the file `/etc/sysctl.d/20-net-rbuffer.conf` as follows + ``` + # This sets the max OS receive-buffer size for all types of connections + net.core.rmem_max=8388608 + ``` + +## Customize the system + +What now you need to do is to customize the installation with your hardware and environment (see the "_Required configuration_" paragraph in [_Networking_](networking.md), [_Bluetooth_](bluetooth.md), [_User Environment_](user-env.md) chapters as well as [_Further Tasks_ chapter](further-tasks.md) ) diff --git a/docs/icub_operating_systems/other-machines/generic-machine-22.04.md b/docs/icub_operating_systems/other-machines/generic-machine-22.04.md new file mode 100644 index 000000000..b30a5aaa0 --- /dev/null +++ b/docs/icub_operating_systems/other-machines/generic-machine-22.04.md @@ -0,0 +1,106 @@ +# Generic iCub environment machines + +This page contains instructions on how to prepare a machine to work in the iCub Subnet environment. This is a basic setup, useful as a starting point to prepare any kind of machine of the iCub ecosystem. + +## Operating System + +You can choose both a Debian or Ubuntu Linux, the currently suggested OS is [Ubuntu 22.04 (Jammy Jellyfish)](http://releases.ubuntu.com/22.04/). + +## User account + +### Users and Passwords + +The default user account is + +**Username** : `icub` +**Password** : `icub` + +If you want to change the default password simply execute (*this works only if you are using persistence*) + +`passwd icub` + +!!! note "root login" + As in any Ubuntu installation, the root user has no password, this means that the direct login (i.e. *ssh root\@icub-head*) is disabled, but you can always do + +`sudo su - ` + + +Add the icub user to the sudoers group, as follows + +`sudo usermod -aG sudo icub` + +## Required and useful Packages + +Please install the following packages (names are correct for Ubuntu 20.04, please check the corresponding package in your distribution): + +` nfs-common python-tk libopencv-dev ntpdate ssh cmake-curses-gui` + +Also install (optional, but very useful) the following packages: + +`vim iperf` + +## Debian Software repository + +!!! warning "for Debian systems" + this step is required only for a Debian machine. + +Enable the **non-free** and **contrib** sources, by editing the file `/etc/apt/sources.list` + +## Network configuration + +You have two options: + +- Static IP address (this option is **mandatory** if there is no DHCP in your subnet - like in the case of the [iCub Console Server](icub-server-laptop.md) - or if your machine is the DHCP server - this is the case of the [iCub Dedicated Server](icub-server-from-scratch.md) ) +- Dynamic DHCP IP address + +### Configuration methods +Usually, if you have a Desktop installed on your machine it's better to use the default desktop network tool (eg. in Ubuntu 22.04 the tool is [Network Manager](https://help.ubuntu.com/community/NetworkManager) ) or using its cli UI `nmtui` very powerfull and easy to use even when conneted via `ssh`. + +Otherwise, you can configure the network interfaces using the command line configuration files (eg. in Ubuntu 22.04 you have to deal with [NETPLAN](https://netplan.io/) ) + +### the HOSTS file +Please check that the file `/etc/hosts` looks as follows: + +``` +127.0.0.1       localhost +127.0.1.1       MACHINE_HOSTNAME.icub.local       MACHINE_HOSTNAME +``` + +where **MACHINE_HOSTNAME** is the hostname of you machine, that should match the file `/etc/hostname` + + +## NTP configuration + +!!! warning "in case of iCub server" + Skip this step in case of [iCub Console Server](icub-server-laptop.md) or [iCub Dedicated Server](icub-server-from-scratch.md) + +You should configure this machine as an NTP client and then configure the NTP service to point to `icub-srv` as an NTP server. + +You can use several different packages to install an NTP client, but we recommend using `systemd-timesyncd` and removing the package `ntp`, if present. + +To configure `timesyncd` the only thing needed is to edit the file `/etc/systemd/timesyncd.conf` adding the line `NTP=10.0.0.1` or your current NTP server IP address. + +Not mandatory but recommanded add also in the same file the line `FallbackNTP=ntp.ubuntu.com` this will be our backup NTP server. + +Finally restart `timesyncd`service + +`sudo systemctl restart systemd-timesyncd` + +## iCub user environment variables + +!!! warning "in case of iCub dedicated server" + Skip this step in case of [iCub Dedicated Server](icub-server-from-scratch.md) + +see [_User Environment_](../icubos/user-env.md) chapter + +## Customize the system + +What now you need to do is to customize the installation with your hardware and environment (see [_User Environment_](../icubos/user-env.md) chapter) + +## Special computers + +In case of special machines (such as the cuda workstation or icub laptop) you must follow further steps in order to complete the installation: + +- [iCub Dedicated Server](icub-server-from-scratch.md) +- [iCub Console Server](icub-server-laptop.md) +- [The nVidia CUDA workstation](cuda-workstation.md) diff --git a/mkdocs.yml b/mkdocs.yml index 16a30b614..f17947cd0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -230,6 +230,8 @@ nav: - Installation: - Installation from pre-built image: icub_operating_systems/icubos/installation-from-image.md - Installation from scratch: icub_operating_systems/icubos/installation-from-scratch.md + - Installation from scratch-22.04: icub_operating_systems/icubos/installation-from-scratch-22.04.md + - Installation from Ansible playbook: icub_operating_systems/icubos/installation-from-ansible-playbook.md - Networking: icub_operating_systems/icubos/networking.md - Bluetooth: icub_operating_systems/icubos/bluetooth.md - User environment: icub_operating_systems/icubos/user-env.md @@ -241,6 +243,7 @@ nav: - Details: icub_operating_systems/pc104/the-icub-live-details.md - The OS on other machines (not on robot): - Generic iCub environment machines: icub_operating_systems/other-machines/generic-machine.md + - Generic iCub environment machines-22.04: icub_operating_systems/other-machines/generic-machine-22.04.md - The iCub Server: - The iCub Dedicated Server: - Summary: icub_operating_systems/other-machines/icub-server-os.md