AwaniOS Installation & Console Dashboard Guide

AwaniOS is a specialized, production-grade cloud operating system built for hyper-converged infrastructure, virtual machine management, and software-defined networking (SDN). It features an interactive TUI Installation Wizard and a comprehensive Console Dashboard (os-tui) for real-time node monitoring, network configuration, Open vSwitch (OVS) Virtual Switch management, and system administration.

---

1. System Installation

1.1 Booting & Initialization

• Booting: Insert the AwaniOS ISO installation media into your bare metal server or virtual machine and boot the system. You will observe the kernel boot sequence and live installer initialization [00:10].
• Welcome Screen: Upon completion, the interactive AwaniOS Installation Wizard launches.
• Warning: Installing AwaniOS will FORMAT AND ERASE ALL DATA on the selected target disk. Press ENTER to acknowledge and proceed [00:27].

1.2 Disk & Network Configuration

• Select Target Disk: Choose the target physical storage device (e.g., /dev/sda or /dev/vda). Use arrow keys to navigate and ENTER to select [00:34].
  • Storage Layout: The installer creates an aligned GPT table featuring a BIOS Boot / EFI System Partition, a boot partition (/boot), and an LVM Volume Group (awan-vg) containing root, swap, and home logical volumes with a 32MB GPT tail reserve.
• Select Primary Network Interface: Choose the active physical NIC for node management (e.g., enp1s0 or eth0) [00:41].
• Select Network Mode:
  • DHCP (Automatic): Receives IP address, gateway, and DNS servers automatically from your network DHCP server [00:47].
  • Static (Manual): Requires entering static IP address with CIDR notation (e.g., 192.168.1.100/24), default gateway (e.g., 192.168.1.1), and DNS nameservers (e.g., 1.1.1.1, 8.8.8.8).

1.3 System Identity & Credentials

• Hostname: Enter a unique node hostname (e.g., awanios-node-01).
• System Password: Enter a secure password for the administrator account (awanio).
• Confirm Password: Re-type the password for verification. Press Tab to switch fields and ENTER to submit [00:54].

1.4 Installation Execution & Reboot

• Configuration Summary: Review the partition scheme, LVM configuration, and network parameters [01:21].
• Execution: Press ENTER to start the automated Curtin installation process. The system formats partitions, extracts the OS filesystem image, and installs GRUB bootloaders [01:32].
• Reboot: Upon completion, press ENTER to reboot the node and remove the installation media [01:52].

---

2. Console Dashboard (os-tui)

After booting the installed AwaniOS node, the system presents the AwaniOS Console Dashboard on tty1.

2.1 Authentication & Security

Log in using the awanio username and the system password configured during installation. Authentications are verified against Linux system shadow credentials via PAM (unix_chkpwd).

2.2 Dashboard Layout & Navigation

The dashboard is split into three main regions:

1. Header Bar (Top): Displays Node Hostname, active user (awanio), and connection status.
2. Sidebar (Left): Vertical menu listing all core management tabs with shortcut numbers (1 to 6).
3. Main Content Panel (Center/Right): Interactive area for viewing statistics and performing configuration tasks.

Global Keyboard Shortcuts

Key	Action
1 – 6	Jump directly to specific tab (1: Overview, 2: Networks, 3: Storages, 4: Services, 5: Terminal, 6: Power)
Tab / Shift+Tab	Cycle forward / backward through tabs
h / l or ← / →	Switch tabs left / right
j / k or ↓ / ↑	Navigate lists and menu items
n	Open Physical NIC Management Wizard (from Networks tab)
m	Open Virtual Switch (VS) Management Wizard (from Networks tab)
u	Open Console TUI Updater modal
q	Quit Console TUI to login prompt

---

3. Detailed Dashboard Modules

3.1 System Overview Tab ([1])

The System Overview tab provides real-time health monitoring of the physical host:

• System Information: Hostname, OS distribution version, Linux Kernel release version, and Uptime duration.
• Hardware Resources: CPU architecture, CPU core count, Load Average (1m, 5m, 15m), and Total/Used Memory.
• Resource Usage Bars: Dynamic progress bars illustrating live CPU utilization and Memory consumption percentages.
• Quick Action Button [u]: Shortcut to launch the TUI Updater modal.

---

3.2 Network & Interface Management ([2])

Press 2 to open the Networks tab. This section displays physical network interfaces, Open vSwitch (OVS) bridges, and virtual ports (vPorts).

3.2.1 Physical NIC Management ([n])

Press n on the Networks tab to configure physical network interface cards:

1. Select Physical Interface: Choose an active interface (e.g., enp1s0, eth0).
2. Choose Configuration Mode:
   • DHCP Mode: Reconfigures Netplan for automatic IPv4/IPv6 lease acquisition (dhcp4: true).
   • Static IP Mode: Reconfigures Netplan with custom static network parameters:
     • IP Address with CIDR: Enter the IP address with CIDR netmask (e.g., 192.168.1.10/24). Note: CIDR prefix is required.
     • Gateway: Default IPv4 routing gateway (e.g., 192.168.1.1).
     • DNS Nameservers: Comma-separated DNS resolver addresses (e.g., 1.1.1.1, 8.8.8.8).
3. State Toggle & Cleanup:
   • Bring interface UP or DOWN.
   • Clear existing IP address assignments.
4. Automated DNS & Resolution Sync:
   • When netplan applies new static DNS settings, AwaniOS automatically enables systemd-resolved and synchronizes nameservers to /etc/resolv.conf to ensure domain name resolution works across all system applications.

---

3.2.2 Virtual Switch (VS) & vPort Management ([m])

AwaniOS integrates Open vSwitch (OVS) for high-performance software-defined networking. Press m on the Networks tab to access the Virtual Switch wizard.

A. Managing VS Bridges

• Create VS Bridge:
  • Bridge Name: Enter a custom bridge name (e.g., br-ex, br-int).
  • Fail Mode: Choose standalone (default L2 switching) or secure (requires SDN controller).
  • STP / RSTP: Toggle Spanning Tree Protocol (STP) or Rapid Spanning Tree Protocol (RSTP) for loop prevention.
• Delete VS Bridge: Removes the OVS bridge and detaches associated interfaces safely.

B. Managing Virtual Ports (vPorts)

• Add System Port (Trunk/Physical NIC):
  • Attach a physical NIC (e.g., eth1) as an uplink system port to an OVS bridge.
  • The physical NIC's IP address is stripped in Netplan and handed over to the OVS pipeline.
• Add Internal vPort:
  • Create internal OVS vPorts (e.g., mgmt0, storage0) for host networking or hypervisor services.
  • Assign 802.1Q VLAN Tags (1–4094) for network segmentation.
  • Assign Static IP addresses directly to the internal vPort.
• Service Tags: Assign specialized AwaniOS service roles to vPorts for automated cluster traffic routing:
  • management — Primary node management and API control plane.
  • storage — Ceph / SAN storage network traffic.
  • migration — Live VM migration network traffic.
  • backup — Data backup and snapshot replication.
  • replication — Storage block replication.
  • shared-heartbeat — Cluster quorum and HA heartbeat.
• Persistent Boot Recovery (awanios-ovs-ports.service): OVS internal ports and service tags configured via os-tui are automatically persisted to /etc/awanios/ovs-internal-ports.conf and re-applied at boot before network initialization.

---

3.3 Storage Management Tab ([3])

Press 3 to open the Storages tab:

• Physical Disks: View detected block devices, disk models, serial numbers, total capacities, and partition tables (/dev/sda, /dev/nvme0n1).
• LVM Volume Groups: Inspect awan-vg storage pool metrics, allocated extents, and free space.
• Logical Volumes: Monitor mount points, filesystem types (ext4, xfs), total sizes, and usage percentages for /, /home, and swap.

---

3.4 Systemd Services Tab ([4])

Press 4 to view active and background system services (vapor, libvirtd, openvswitch-switch, systemd-networkd, systemd-resolved, ceph):

• Filter & Search: Press / to open the real-time search box and type service names.
• Service Status: View load state, active state (active/inactive), and sub-state (running/exited).
• Service Control Actions:
  • Select a service and press ENTER to view detailed unit logs.
  • Quick action controls: Start, Stop, Restart, Enable, Disable.
• Refresh List: Press R to reload service states.

---

3.5 Embedded Terminal ([5])

Press 5 to open the built-in pseudo-terminal shell:

• Launches an interactive Bash shell session directly inside the console UI under the awanio user account.
• Supports standard terminal commands, sudo privileges, text editors (vim, nano), and CLI utilities (awctl, kubectl, virsh, ovs-vsctl, ceph).
• Press ctrl+d or type exit to close the shell session and return to the TUI menu.

---

3.6 Power Management ([6])

Press 6 to open the node Power management tab:

• Reboot Node: Soft-reboots the operating system safely (systemctl reboot).
• Shutdown Node: Safely stops all virtual machines, unmounts filesystems, and powers off the hardware (systemctl poweroff).
• Requires confirmation step to prevent accidental shutdowns.

---

4. Console TUI Updates

AwaniOS features built-in self-updating capabilities for the console dashboard.

4.1 In-App TUI Updater (u key)

1. Press u from any tab in the console dashboard (or click [u] Update TUI on Overview).
2. The TUI queries https://storage.awan.io/assets/tui-version.json and compares online release metadata with local BuildID.
3. If an update is available, press [Enter] to begin:
   • Downloads the latest compiled os-tui binary.
   • Creates a fallback backup (/usr/local/bin/os-tui.bak).
   • Replaces /usr/local/bin/os-tui atomically.
   • Restarts the TUI session automatically (getty@tty1.service) in 1 second without restarting the host OS.

4.2 Manual Command Line Update

Alternatively, system administrators can update the console dashboard from a remote SSH terminal or shell session:

curl -sSL https://storage.awan.io/assets/awanios-tui-update.sh | sudo bash