# Console - Serial Console

> Configuring the VyOS serial console - ttyS0 setup, baud rate, out-of-band management and device diagnostics for physical and cloud deployments

Source: https://opennix.org/en/docs/vyos/system/vyos-console/


## Console - Serial Console

## Overview

The serial console in VyOS provides a mechanism for remotely managing the router through a serial port. This is especially useful in the following scenarios:

- **Out-of-band management**: Access to the device independent of the state of the network interfaces
- **Boot diagnostics**: Monitoring the system boot process and identifying problems at an early stage
- **Emergency recovery**: Access to the system when the network configuration is not working
- **Cloud platforms**: Access to virtual machines through the cloud provider's web console
- **Bare-metal servers**: Managing physical servers through KVM or IPMI

The serial console is not a necessity for ordinary users, but it becomes critically important for system administrators working with server hardware or cloud infrastructures.

## Supported Console Devices

VyOS supports various types of console devices:

### Serial Devices (ttySN)

Standard serial ports built into server hardware:

- `ttyS0` - First serial port (COM1)
- `ttyS1` - Second serial port (COM2)
- `ttyS2` - Third serial port (COM3)
- `ttyS3` - Fourth serial port (COM4)

These ports are typically used on physical servers and some virtual machines.

### USB Serial Devices (ttyUSBX)

USB-to-serial adapters and converters:

- `ttyUSB0` - First USB serial adapter
- `ttyUSB1` - Second USB serial adapter
- `ttyUSBX` - Additional USB adapters

USB adapters are useful for devices without built-in serial ports or when additional console connections are required.

### Virtual Consoles

Specialized console devices for virtualization:

- `hvc0` - Xen HVM console (for Xen virtualization)

## Basic Console Configuration

### Configuring the Serial Console

Basic serial console configuration on ttyS0 with default settings:

```bash
configure
set system console device ttyS0
commit
save
```

### Configuring the Baud Rate

VyOS supports the following data transfer rates:

- 1200 bps
- 2400 bps
- 4800 bps
- 9600 bps (standard rate)
- 19200 bps
- 38400 bps
- 57600 bps
- 115200 bps (high speed, used by default)

#### Example: Console at 9600 bps

```bash
configure
set system console device ttyS0 speed 9600
commit
save
```

#### Example: Console at 115200 bps

```bash
configure
set system console device ttyS0 speed 115200
commit
save
```

#### Example: USB console at 38400 bps

```bash
configure
set system console device ttyUSB0 speed 38400
commit
save
```

### Recommendations for Choosing a Baud Rate

**9600 bps**:
- The most compatible rate
- Recommended for older hardware
- Minimal risk of data transmission errors
- Slow for large volumes of text

**115200 bps**:
- High data transfer rate
- Recommended for modern hardware
- Fast output of logs and commands
- May be unstable on poor-quality cables or USB adapters

**The golden mean (38400-57600 bps)**:
- Optimal balance of speed and stability
- Suitable for most scenarios
- Good performance with a reliable connection

## Console Rotation

VyOS supports configuring multiple console devices simultaneously. This is useful for redundancy or access through different physical interfaces.

### Example: Multiple Serial Consoles

```bash
configure

# First console on ttyS0 (primary)
set system console device ttyS0 speed 115200

# Second console on ttyS1 (backup)
set system console device ttyS1 speed 115200

# USB console for local access
set system console device ttyUSB0 speed 9600

commit
save
```

### Example: Combination of Virtual and Physical Consoles

```bash
configure

# Xen virtual console (for the cloud platform)
set system console device hvc0 speed 115200

# Physical serial console (for IPMI/KVM)
set system console device ttyS0 speed 115200

commit
save
```

## Boot Console Configuration

### GRUB Serial Console

To access the GRUB bootloader through the serial console, you need to modify the GRUB configuration. This allows you to control the system boot process through the serial port.

#### Editing the GRUB Configuration

```bash
# Edit the GRUB configuration
sudo vi /boot/grub/grub.cfg
```

Add the following lines to the beginning of the file (after the header):

```bash
serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1
terminal_input serial console
terminal_output serial console
```

#### Kernel Boot Parameters

Make sure the kernel boot parameters include the console settings:

```bash
# Add the following to the linux parameters:
console=tty0 console=ttyS0,115200n8
```

Full example of a GRUB entry:

```bash
menuentry 'VyOS' {
    load_video
    insmod gzio
    insmod part_msdos
    insmod ext2
    set root='hd0,msdos1'
    echo 'Loading VyOS...'
    linux /boot/vmlinuz root=/dev/sda1 ro console=tty0 console=ttyS0,115200n8 quiet
    echo 'Loading initial ramdisk...'
    initrd /boot/initrd.img
}
```

#### Persistent GRUB Configuration

To preserve the changes across system updates, edit the default configuration file:

```bash
# Edit the default configuration file
sudo vi /etc/default/grub
```

Add or modify the following parameters:

```bash
GRUB_CMDLINE_LINUX_DEFAULT="console=tty0 console=ttyS0,115200n8"
GRUB_SERIAL_COMMAND="serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1"
GRUB_TERMINAL="serial console"
```

Update the GRUB configuration:

```bash
sudo update-grub
```

## Examples for Cloud Platforms

### Yandex Cloud: Access via Serial Console

Yandex Cloud provides access to the serial console of virtual machines through the web interface. VyOS in Yandex Cloud uses a pre-configured serial console.

#### VyOS Configuration for Yandex Cloud

Standard configuration for Yandex Cloud (usually already set up in the image):

```bash
configure

# Configuring the serial console for Yandex Cloud
set system console device ttyS0 speed 9600

commit
save
```

#### Access via the Yandex Cloud Web Console

1. Open the Yandex Cloud Console: https://console.cloud.yandex.ru
2. Go to the "Compute Cloud" section
3. Select the VyOS virtual machine
4. Click the "Connect" button and select "Serial Console"
5. In the terminal that opens, press Enter to activate the console

#### Access via the Yandex Cloud CLI

```bash
# Connecting to the serial console via CLI
yc compute instance serial-port-output <instance-id>

# Retrieving the last 1000 lines of output
yc compute instance serial-port-output <instance-id> --lines 1000

# Interactive connection (requires an SSH key)
yc compute connect-to-serial-port --instance-id <instance-id>
```

#### Configuring Serial Console Logging in Yandex Cloud

```bash
configure

# Enable system logging
set system syslog global facility all level info

# Configure console output
set system console device ttyS0 speed 9600

commit
save
```

#### Yandex Cloud Serial Console Specifics

- **Speed**: Use 9600 bps for stable operation
- **Availability**: The serial console is available even when there are network problems
- **History**: Yandex Cloud stores the console output history (up to 64 KB)
- **Security**: Access to the serial console requires permissions on the virtual machine

### VK Cloud: Serial Console for Bare-Metal Servers

VK Cloud (formerly Mail.ru Cloud Solutions) provides access to the serial console for bare-metal servers through the IPMI/KVM interface.

#### VyOS Configuration for VK Cloud Bare-Metal

```bash
configure

# Configuring the serial console
set system console device ttyS0 speed 115200

# Optional: an additional console for redundancy
set system console device ttyS1 speed 115200

commit
save
```

#### Access via IPMI Console

1. Log in to the VK Cloud control panel
2. Go to the "Servers" -> "Bare-metal" section
3. Select the server with VyOS
4. Click "IPMI Console" or "KVM Console"
5. The serial console will be available in the window that opens

#### Configuration for Remote IPMI Access

```bash
configure

# Configuring a high-speed console for IPMI
set system console device ttyS0 speed 115200

# Enable SSH for alternative access
set service ssh port 22
set service ssh listen-address 0.0.0.0

commit
save
```

#### IPMI Serial-over-LAN (SOL)

For direct access through IPMI Serial-over-LAN:

```bash
# From the client machine, connect to IPMI
ipmitool -I lanplus -H <ipmi-ip> -U <username> -P <password> sol activate
```

The VyOS configuration must use a speed of 115200 bps for SOL:

```bash
configure
set system console device ttyS0 speed 115200
commit
save
```

## Verifying the Console Configuration

### Viewing the Current Configuration

```bash
# Show the system console configuration
show configuration system console

# Example output:
# console {
#     device ttyS0 {
#         speed 115200
#     }
# }
```

### Checking Active Console Devices

```bash
# Show active TTY devices
show system tty

# Alternative method (in operational mode)
run show system tty
```

### Viewing System Console Logs

```bash
# View the serial console logs
show log tail

# Search for messages related to the console
show log | match console
```

### Testing Console Output

```bash
# Print a test message to the console
echo "Test message to console" | tee /dev/ttyS0

# Verify console operation through dmesg
show system kernel-messages | match ttyS
```

### Checking Serial Port Parameters

```bash
# View serial port parameters (from operational mode)
run show interfaces serial ttyS0

# Detailed information via stty (from the shell)
sudo stty -F /dev/ttyS0 -a
```

## Troubleshooting

### Problem: The console does not respond

**Symptoms**: No output on the serial console after connecting.

**Solutions**:

1. Check the speed (baud rate) settings on both ends of the connection:

```bash
# Make sure the console speed matches the terminal program
show configuration system console device ttyS0
```

2. Verify that the device is active:

```bash
# Check the device status
run show system tty
```

3. Restart getty for the console:

```bash
# From shell mode
sudo systemctl restart serial-getty@ttyS0.service
```

4. Check the physical cable connection (for bare-metal).

### Problem: Garbled characters on the console

**Symptoms**: The console output contains incorrect characters or unreadable text.

**Cause**: A mismatch in the speed, parity, or data bit settings.

**Solutions**:

1. Set the standard speed of 9600 bps:

```bash
configure
set system console device ttyS0 speed 9600
commit
save
```

2. Check the terminal program parameters:
   - Data bits: 8
   - Parity: None
   - Stop bits: 1
   - Flow control: None (or Hardware)

3. Try other speeds one by one:

```bash
configure
set system console device ttyS0 speed 38400
commit
# Test the console
# If it does not work, try another speed
set system console device ttyS0 speed 57600
commit
```

### Problem: The USB console is not detected

**Symptoms**: The USB-to-serial adapter is not displayed as ttyUSB0.

**Solutions**:

1. Check that the USB device is recognized:

```bash
# Check USB devices
run show system usb

# Or via lsusb
lsusb
```

2. Check that the drivers are loaded:

```bash
# Check the loaded modules for USB serial
lsmod | grep usbserial
lsmod | grep ftdi
lsmod | grep pl2303
```

3. Check dmesg for USB-related messages:

```bash
run show system kernel-messages | match -i usb
run show system kernel-messages | match ttyUSB
```

4. Try another USB port or adapter.

### Problem: The console works, but GRUB is not displayed

**Symptoms**: The VyOS console works, but the GRUB menu is not visible during boot.

**Solution**: Configure GRUB to output to the serial console:

```bash
# Edit the GRUB configuration
sudo vi /etc/default/grub

# Add the parameters:
GRUB_CMDLINE_LINUX_DEFAULT="console=tty0 console=ttyS0,115200n8"
GRUB_SERIAL_COMMAND="serial --unit=0 --speed=115200"
GRUB_TERMINAL="serial console"

# Update GRUB
sudo update-grub

# Reboot the system
reboot now
```

### Problem: Slow console output

**Symptoms**: Commands execute quickly, but the output appears slowly.

**Solutions**:

1. Increase the transfer speed:

```bash
configure
set system console device ttyS0 speed 115200
commit
save
```

2. Check the flow control settings:

```bash
# Disable flow control (in shell mode)
sudo stty -F /dev/ttyS0 -crtscts -ixon -ixoff
```

3. Reduce the volume of output:

```bash
# Instead of the full show configuration
show configuration commands

# Use grep to filter
show configuration | match interface
```

### Problem: The console loses connection

**Symptoms**: The console connection drops periodically.

**Solutions**:

1. For cloud platforms, check the timeout settings:

```bash
# Increase the timeout for SSH sessions
configure
set service ssh client-keepalive-interval 60
commit
save
```

2. For physical connections:
   - Check the cable quality
   - Use shielded cables
   - Reduce the speed to 9600 bps

3. Configure automatic reconnect in the terminal program.

## Best Practices

### Console Security

1. **Restricting access to the physical console**:

```bash
configure

# Configure the console session timeout
set system login timeout 300

# Require authentication for the console
set system console device ttyS0

commit
save
```

2. **Logging console sessions**:

```bash
configure

# Enable auditing of system events
set system syslog global facility auth level info
set system syslog global facility authpriv level info

# Send logs to a remote server
set system syslog host 192.168.1.100 facility auth level info

commit
save
```

3. **Protecting GRUB with a password** (optional):

```bash
# Create a password hash for GRUB
grub-mkpasswd-pbkdf2

# Add to /etc/grub.d/40_custom
set superusers="root"
password_pbkdf2 root <generated-hash>
```

### Performance and Reliability

1. **Choosing the optimal speed**:
   - Local connections: 115200 bps
   - Cloud platforms: 9600-38400 bps
   - Long cables: 9600-19200 bps

2. **Console redundancy**:

```bash
configure

# Configure multiple console devices
set system console device ttyS0 speed 115200
set system console device ttyS1 speed 115200

# For cloud environments
set system console device hvc0 speed 115200
set system console device ttyS0 speed 9600

commit
save
```

3. **Monitoring the console state**:

```bash
# Create a console check script
configure

set system task-scheduler task check-console executable path /config/scripts/check-console.sh
set system task-scheduler task check-console interval 5m

commit
save
```

Example of the `/config/scripts/check-console.sh` script:

```bash
#!/bin/bash
# Check the health of the serial console

CONSOLE_DEVICE="/dev/ttyS0"
LOG_FILE="/var/log/console-check.log"

if [ -e "$CONSOLE_DEVICE" ]; then
    echo "$(date): Console device $CONSOLE_DEVICE is present" >> "$LOG_FILE"

    # Check whether writing is possible
    if echo "test" > "$CONSOLE_DEVICE" 2>/dev/null; then
        echo "$(date): Console device $CONSOLE_DEVICE is writable" >> "$LOG_FILE"
    else
        echo "$(date): WARNING: Console device $CONSOLE_DEVICE is not writable" >> "$LOG_FILE"
        # Restart getty
        systemctl restart serial-getty@ttyS0.service
    fi
else
    echo "$(date): ERROR: Console device $CONSOLE_DEVICE not found" >> "$LOG_FILE"
fi
```

### Documenting the Configuration

1. **Adding comments to the configuration**:

```bash
configure

# Add a description of the console configuration
comment system console device ttyS0 "Primary serial console for IPMI/KVM access"
comment system console device ttyS0 speed "115200 bps for high-speed output"

commit
save
```

2. **Saving configuration backups**:

```bash
# Create a backup with a description
save /config/backup/config-with-console-$(date +%Y%m%d).boot
```

### Cloud Platforms

1. **Yandex Cloud**: Use 9600 bps for stability:

```bash
configure
set system console device ttyS0 speed 9600
commit
save
```

2. **VK Cloud Bare-Metal**: Use 115200 bps for IPMI SOL:

```bash
configure
set system console device ttyS0 speed 115200
commit
save
```

3. **Hybrid configuration** (virtual + physical):

```bash
configure

# Virtual console for the cloud
set system console device hvc0 speed 115200

# Physical console for backup access
set system console device ttyS0 speed 9600

commit
save
```

## Advanced Scenarios

### Automatic Console Configuration During Deployment

Example of a script for automatically configuring the console depending on the platform:

```bash
#!/bin/vbash
# /config/scripts/configure-console.sh
# Automatic console configuration depending on the platform

source /opt/vyatta/etc/functions/script-template

# Detecting the platform
if [ -e /sys/hypervisor/type ]; then
    HYPERVISOR=$(cat /sys/hypervisor/type)
else
    HYPERVISOR="none"
fi

# Configuration depending on the hypervisor
case $HYPERVISOR in
    xen)
        # Yandex Cloud or another Xen platform
        configure
        set system console device hvc0 speed 115200
        set system console device ttyS0 speed 9600
        commit
        save
        ;;
    kvm)
        # KVM virtualization
        configure
        set system console device ttyS0 speed 115200
        commit
        save
        ;;
    *)
        # Bare-metal or unknown platform
        configure
        set system console device ttyS0 speed 115200
        set system console device ttyS1 speed 115200
        commit
        save
        ;;
esac

echo "Console configured for platform: $HYPERVISOR"
```

### Integration with Monitoring Systems

Example of exporting console metrics for Prometheus:

```bash
#!/bin/bash
# /config/scripts/console-metrics.sh
# Export console metrics for monitoring

METRICS_FILE="/var/tmp/console_metrics.prom"

# Check for the presence of console devices
console_present=0
if [ -e /dev/ttyS0 ]; then
    console_present=1
fi

# Count the messages in the console logs (over the last hour)
console_messages=$(journalctl -u serial-getty@ttyS0.service --since "1 hour ago" | wc -l)

# Write the metrics
cat > "$METRICS_FILE" << EOF
# HELP vyos_console_present Console device presence (1=present, 0=absent)
# TYPE vyos_console_present gauge
vyos_console_present{device="ttyS0"} $console_present

# HELP vyos_console_messages_total Total console messages in last hour
# TYPE vyos_console_messages_total counter
vyos_console_messages_total{device="ttyS0"} $console_messages
EOF
```

## References

- [VyOS Documentation: Console Configuration](https://docs.vyos.io/en/latest/configuration/system/console.html)
- [Yandex Cloud: Serial Console](https://cloud.yandex.ru/docs/compute/operations/serial-console/)
- [VK Cloud: Bare-Metal Servers](https://mcs.mail.ru/help/bare-metal-servers/servers)
- [Serial Console Best Practices](https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html)

## Conclusion

The serial console is a critically important tool for administering VyOS routers, especially in server and cloud environments. Proper console configuration provides:

- Reliable out-of-band access for emergency recovery
- The ability to diagnose system boot problems
- Convenient access through cloud platforms (Yandex Cloud, VK Cloud)
- A backup management channel during network problems

Follow the recommendations for choosing the data transfer rate, configure redundancy of console devices, and document the configuration to simplify support and troubleshooting.